Pylon can notify your application when key events occur inside the platform by delivering signed webhooks over HTTPS.

Configuration

Webhook delivery is configured per customer: an HTTPS callback URL, the set of subscribed events, and a signing secret shared between Pylon and your application. Contact Pylon to enable webhooks for your integration or to rotate your signing secret.

Delivery

Events are delivered as POST requests with a JSON body and these headers:

Header	Meaning
X-Pylon-Signature	Versioned HMAC signature of the request: v1=<hex digest>.
X-Pylon-Timestamp	Unix time (seconds) at which the delivery was signed.
X-Pylon-Idempotency-Key	Stable identifier for the event; identical across retries.

Delivery is at-least-once. A 2xx response acknowledges the event. Any other response is treated as a failed delivery and retried with exponential backoff, except statuses in the 4xx range other than 429, which mark the delivery as permanently failed. Because retries can produce duplicate deliveries, deduplicate on X-Pylon-Idempotency-Key (also present in the payload as idempotencyKey).

Verifying signatures

Verify every delivery before trusting it:

1. Read the raw request body exactly as received — do not re-serialize the JSON.
2. Concatenate the value of X-Pylon-Timestamp, a period (.), and the raw body.
3. Compute the HMAC-SHA256 hex digest of that string using your signing secret.
4. Compare v1=<digest> against X-Pylon-Signature with a constant-time comparison.
5. Reject deliveries whose timestamp is more than 5 minutes from your clock. The timestamp is bound into the signature, so a replayed request cannot present a fresher one.

import { createHmac, timingSafeEqual } from "node:crypto";
            
            function verifyPylonWebhook(headers, rawBody, secret) {
              const timestamp = headers["x-pylon-timestamp"] ?? "";
              const signature = headers["x-pylon-signature"] ?? "";
              if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
                return false;
              }
              const digest = createHmac("sha256", secret)
                .update(`.`)
                .digest("hex");
              const expected = Buffer.from(`v1=`);
              const received = Buffer.from(signature);
              return (
                expected.length === received.length &&
                timingSafeEqual(expected, received)
              );
            }
            

Event: contributor.created

Fired when a contributor — for example a borrower — is created, including when a loan officer creates the borrower from Pylon's Command Center. The payload identifies the surface the contributor was created from via source, so a host application can react specifically to contributors originating in the Command Center.

Field	Type	Meaning
event	string	Always contributor.created.
contributorId	string	The contributor's Pylon ID — the identifier to store.
dealId	string or null	The deal in scope at creation, when one exists.
role	string	The contributor's role, e.g. BORROWER.
customerId	string	The Pylon customer the contributor belongs to.
source	string or null	Creation surface: COMMAND_CENTER, MORTGAGE_PORTAL, or ELEMENTS. null for creations that predate source attribution.
createdAt	string	ISO-8601 creation time.
idempotencyKey	string	<contributorId>:contributor.created, stable across retries and re-emits.

{
  "event": "contributor.created",
  "contributorId": "cont_2q3X8x1JQvXhYw5mZk7Rr",
  "dealId": "morwor_5b9Kd2mPnWcVtL4sYq8Hh",
  "role": "BORROWER",
  "customerId": "cust_7f1Ns6vBqTgXjM3wZp2Ee",
  "source": "COMMAND_CENTER",
  "createdAt": "2026-07-02T17:24:08.000Z",
  "idempotencyKey": "cont_2q3X8x1JQvXhYw5mZk7Rr:contributor.created"
}