Skip to main content

Build Webhook

When you set deliver.webhookUrl on from-url, the platform POSTs lifecycle events to that URL — at minimum the terminal event (ready or failed). This powers “email-me-a-link” UX without the client holding an SSE connection. The body is a ProvisioningEvent and is HMAC-signed so you can verify authenticity.

Delivery

The HMAC is HMAC-SHA256 over the raw request body, keyed with the platform’s webhook secret (provisioned with your API key / org). Respond 2xx quickly to acknowledge; non-2xx triggers a retry.

Example Payload

Verifying the Signature (Node / Express)

Always verify the signature against the raw body before trusting the payload. Use a constant-time comparison.
Node / Express

curl (compute a test signature)

curl
Compute the HMAC over the raw bytes of the request body — re-serializing parsed JSON (different key order or whitespace) will change the digest and fail verification. Capture the raw body before any JSON middleware parses it.

Status Values & Error Model

The webhook body is a ProvisioningEvent — see the full ProvisioningStatus and ProvisioningErrorCode references. On a failed event, branch on error.retryable.