Build Webhook
When you setdeliver.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
Status Values & Error Model
The webhook body is aProvisioningEvent — see the full
ProvisioningStatus
and
ProvisioningErrorCode
references. On a failed event, branch on error.retryable.
