Assinafy Webhook Payloads API

This section documents the HTTP request your endpoint receives whenever a subscribed event is triggered, and the shape of the JSON body sent for each event type. ### Delivery contract When an event occurs, we send an HTTP `POST` request to every active webhook endpoint subscribed to that event. Each endpoint is delivered to independently: a slow or failing endpoint does not delay the others, and each has its own failure count. | Property | Value | |----------|-------| | Method | `POST` | | Content-Type | `application/json` | | Connection header | `close` | | `webhook-id` header | Message ID, identical on every attempt of the same event to the same endpoint. Use it to deduplicate. | | `webhook-timestamp` header | Unix timestamp (seconds) of the attempt. | | `webhook-signature` header | Only when signing is enabled on the endpoint. See **Verifying signatures**. | | Success criteria | Any `2xx` response | | `User-Agent` header | `Assinafy-Webhooks/1.0` | | Attempts | Up to 6 per event, about 10 minutes apart. A connection error, a timeout, a `408`, a `429` or a `5xx` is retried; any other status is final. | | Pause | After 10 failed deliveries in a row the endpoint is paused (`is_held` on the endpoint): nothing is sent to it, and we probe it with the oldest event it missed after 3 minutes, then 15, then 60, then every 6 hours. The probe that gets through lifts the pause and the events it missed are delivered oldest first. Editing the endpoint's URL, or sending `is_active: true`, lifts the pause too. | | Retry endpoint | **Retry webhook delivery** sends one delivery now, even while the endpoint is paused; a delivery that gets through lifts the pause. | | Response capture | We store the first 2000 characters of your response body for debugging (see **List webhook deliveries**). Delivery entries are kept for 7 days. | Your endpoint must respond within a reasonable time and return a `2xx` status. Non-`2xx` responses, connection errors and timeouts are all failed deliveries and count toward the pause; each delivery entry says whether another attempt follows (`will_retry`). ### Verifying signatures Enable signing on an endpoint (`signing_enabled: true`) and every delivery carries a signature that proves it came from us and was not altered or replayed. Signatures follow the [Standard Webhooks](https://www.standardwebhooks.com) specification, so any Standard Webhooks library can verify them; the secret is returned once, as `secret`, in the **Create webhook endpoint** response, and can be read again with **Get webhook endpoint signing secret**. OAuth applications cannot call that endpoint: store the secret from the create response, and if it is lost, get a new one with **Rotate webhook endpoint signing secret**. Turning signing on with **Update webhook endpoint** also returns the new secret once. To verify by hand: 1. Take the **raw** request body, exactly as received (do not re-serialize the parsed JSON). 2. Build the signed content `{webhook-id}.{webhook-timestamp}.{body}`. 3. Base64-decode the part of the secret after the `whsec_` prefix and compute the HMAC-SHA256 of the signed content with it. Base64-encode the result. 4. `webhook-signature` holds one or more space-separated `v1,` entries; accept the request if any of them equals your value (use a constant-time comparison). 5. Reject requests whose `webhook-timestamp` is more than a few minutes away from your clock, to prevent replays. ```php $secret = base64_decode(substr($endpointSecret, strlen('whsec_'))); $signedContent = $headers['webhook-id'] . '.' . $headers['webhook-timestamp'] . '.' . $rawBody; $expected = 'v1,' . base64_encode(hash_hmac('sha256', $signedContent, $secret, true)); $valid = false; foreach (explode(' ', $headers['webhook-signature']) as $signature) { $valid = $valid || hash_equals($expected, $signature); } $fresh = abs(time() - (int) $headers['webhook-timestamp']) <= 300; ``` Rotating the secret (**Rotate webhook endpoint signing secret**) takes effect immediately: deliveries sent after the rotation are signed only with the new secret. ### Common envelope Every webhook body shares the same top-level structure: | Field | Type | Description | |-------|------|-------------| | `id` | integer | Internal activity ID that produced this event. To deduplicate retries, prefer the `webhook-id` header, which also tells deliveries of the same event to different endpoints apart. | | `event` | string | Event type identifier. See the catalog below and the **List webhook event types** endpoint. | | `message` | string \\| null | Human-readable message describing the event. May contain token placeholders. Can be `null`. | | `payload` | object \\| null | Event-specific parameters. Keys vary per event — see the catalog. Can be `null`. | | `origin` | object \\| null | Where the action was triggered from, when available: `{ ip, user-agent }`. | | `created_at` | integer | Unix timestamp (seconds) when the event was recorded. | | `subject` | object | The entity that performed the action. Polymorphic — see below. | | `object` | object | The entity the action was performed on. Polymorphic — see below. | | `account_id` | string | The ID of the account that owns this event. Always present. | ### About `subject` and `object` Both are **polymorphic**: their shape depends on which entity they represent. We always add a `type` property with the entity class name, one of `User`, `Signer`, `Account`, `Document`, or `Template`. The remaining properties match the same fields the REST API returns for that resource. The `object` is serialized with its extra relationships expanded (e.g. a `Document` includes `assignment` and `pages`); the `subject` carries its base fields only. Whenever `subject` or `object` is an `Account`, the `integration` property (which includes dispatch history) is removed before sending. For `document_ready`, `document_processing_failed` and `template_processing_failed`, the `subject` is the `Account` itself — these events are emitted by the system when processing finishes, not by a particular user. ### Event catalog Each event also has its own entry under **Webhooks** with a complete example body. | Event | Subject | Object | `payload` keys | Description | |-------|---------|--------|----------------|-------------| | `document_uploaded` | User | Document | — | The user uploaded a new document. | | `document_metadata_ready` | User | Document | — | The document was normalized to PDF and its pages are available. | | `document_prepared` | User | Document | — | The user prepared a document (fields assigned to signers). | | `assignment_created` | User | Document | `user_name`, `user_email`, `user_telephone` | The user created an assignment for the document. Includes a snapshot of the creator profile. | | `document_ready` | Account | Document | — | The document was certificated after every signer signed (and, when a signer's identity was under review, after the account approved it). | | `document_processing_failed` | Account | Document | `error_message` | The document could not be processed. | | `signature_requested` | User | Document | `signer_full_name`, `signer_email`, `signer_whatsapp_phone_number`, `notification_method` | The user requested a signer to sign the document. | | `signer_created` | User | Signer | `signer_full_name` | The user created a new signer. | | `signer_email_verified` | Signer | Document | `signer_full_name`, `signer_email` | The signer's email was verified through a code linked to the document. | | `signer_whatsapp_verified` | Signer | Document | `signer_full_name`, `signer_whatsapp_phone_number` | The signer's WhatsApp number was verified through a code linked to the document. | | `signer_data_confirmed` | Signer | Document | `signer_full_name`, `signer_email`, `signer_whatsapp_phone_number`, `verification_method` | The signer confirmed their data before signing. | | `signer_viewed_document` | Signer | Document | `signer_full_name` | The signer opened the document for the first time. | | `signer_identity_verified` | Signer | Document | `signer_full_name`, `evidence` (when available) | The signer passed identity-document verification, directly or after the account's review. | | `signer_identity_verification_failed` | Signer | Document | `signer_full_name`, `reason` | The identity-document verification ended without approval. | | `signer_identity_review_required` | Signer | Document | `signer_full_name`, `reason_codes` | The verification awaits the account's review. The signer can still sign; the document is certificated only after the account approves (status `pending_identity_review` once every signer has signed). | | `signer_identity_review_approved` | Signer | Document | `signer_full_name`, `reviewer_id`, `reviewer_name`, `reason_codes` | A user of the account approved the signer's identity after review. | | `signer_identity_review_rejected` | Signer | Document | `signer_full_name`, `reviewer_id`, `reviewer_name`, `note` | A user of the account rejected the signer's identity after review. The document is cancelled; `user_rejected_document` follows. | | `signer_signed_document` | Signer | Document | `signer_full_name` | The signer signed the document. | | `signer_rejected_document` | Signer | Document | `signer_full_name` | The signer refused to sign the document. | | `user_rejected_document` | User | Document | `user_name` | The document was cancelled by a user of the account. | | `template_created` | User | Template | — | The user created a new template. | | `template_processed` | User | Template | — | A template's metadata was processed and is ready for use. | | `template_processing_failed` | Account | Template | `error_message` | A template could not be processed. | `assignment_created` and `document_metadata_ready` have no guaranteed ordering: under the virtual pre-metadata flow, `assignment_created` may fire before `document_metadata_ready`. Treat any unknown field as a forward-compatible addition.