Webhooks Integration Guide

Webhooks let Sadq automatically notify your server (via an HTTP POST) when envelope/signing events happen, instead of you having to poll the status endpoint.

All webhook endpoints require a Bearer token (Authorization: Bearer {token}, obtained from POST /Authentication/Authority/Token).

Base URLs:

• Sandbox: https://sandbox-api.sadq-sa.com
• Production: https://api.sadq-sa.com

Note: all JSON field names below are camelCase (webhookUrl, headerToken, isDefault, etc.) — this matches the live API, not PascalCase.

1. Create a webhook

Body:

Response:

Save the returned id — you'll need it if you ever want to target this specific webhook instead of the default one (see section 7).

Note on headerToken: whatever value you put here, Sadq attaches it as the Authorization header when it calls your webhookUrl. Use this to verify that the incoming callback genuinely came from Sadq.

2. Create multiple webhooks at once

Body: an array of the same object shape as section 1.

Returns: an array of the created webhook objects, in the same order.

3. List / get a webhook

List all webhooks on the account:

No body/params. Returns every webhook on the account, including which one has isDefault: true.

Get a single webhook by ID:

4. Update a webhook

Body:

Note: this call doesn't let you change headerToken — that's set when the webhook is created.

5. Delete a webhook

Once deleted, that webhook stops receiving callbacks. Any envelope still referencing its webhookId will fall back to the account default (if one exists).

6. The default webhook

You can create as many webhooks as you like, but only one webhook can actually be used as the default at a time.

• If you set isDefault: true on more than one webhook, Sadq does not call all of them — it picks and calls only one default webhook.
• Whenever you initiate an envelope without explicitly specifying a webhook, Sadq falls back to this single default webhook.

So if you need multiple integrations listening for events, don't rely on multiple "default" webhooks — create separate (non-default) webhooks and target them explicitly per envelope instead, as shown next.

7. Calling a specific webhook (instead of the default)

If you don't want a particular envelope's events to go to the default webhook, pass that webhook's id as webhookId when you initiate the envelope. Sadq will then call that specific webhook for events on this envelope instead of the default one.

Supported on:

• POST /api/v1/envelopes/initiate
• POST /api/v1/envelopes/initiate-base64
• POST /api/v1/envelopes/initiate-by-template
• POST /api/v1/envelopes/bulk/initiate-base64

Example (initiate-base64):

If webhookId is omitted, Sadq uses the account's default webhook (see section 6).

8. What you receive on your endpoint (the callback payload)

When an event fires, Sadq sends a POST to your webhookUrl with this JSON body:

Key fields: RequestId (the envelope/request ID — use this for recall and logs lookups), Status (envelope status code), Files (signed file(s), base64-encoded), Signatory (per-signer status, name, contact info, auth type, rejection reason if any).

Your endpoint should check the Authorization header against the headerToken you configured to confirm the call genuinely came from Sadq, then respond with a 2xx status.

9. Retry a failed delivery (recall)

If a delivery to your endpoint failed (server down, timeout, non-2xx response, etc.), you can ask Sadq to resend it instead of re-triggering the whole envelope:

Body:

10. Get webhook delivery logs

Use this to troubleshoot — see what was sent, what came back, and whether the delivery succeeded or failed.

This is a GET request but, per the live docs, it takes its filters in a JSON body (not query string):

Response:

Each log entry tells you the event's requestId, when it was sent, the resulting webhookStatus, the HTTP status your server returned, and any failure reasons. If a delivery shows as failed, grab its requestId and call recall (section 9) to retry it.

11. Doing all of this from the Sadq portal

Everything above is also available without writing code, directly in the Sadq web portal, under your account/integration settings:

• Create a webhook — open the Webhooks section, click "Add Webhook," enter the target URL and (optionally) a header token, and choose whether it should be the default. The portal calls the same POST /api/v1/webhooks endpoint under the hood.
• Test a webhook — the portal lets you send a test event to your URL so you can confirm your endpoint is reachable and correctly validates the Authorization header, before you wire it into a real envelope flow.
• View logs — the Webhooks section shows a logs/activity tab listing every delivery attempt (event, status, response time, errors) for each webhook, equivalent to GET /api/v1/webhooks/logs. From there you can also trigger a retry on a failed delivery, equivalent to POST /api/v1/webhooks/recall.
• Edit / delete / set default — the same list view lets you edit a webhook's URL, switch which webhook is marked default, or delete one — equivalent to the PUT and DELETE endpoints above.

This is useful for quick setup and debugging, but for anything automated (e.g. provisioning a webhook per customer/environment) you'll still want to use the API directly.

12. End-to-end flow

1. Authenticate — POST /Authentication/Authority/Token → get Bearer token.
2. Register a webhook (once) — POST /api/v1/webhooks with webhookUrl (and optionally headerToken, isDefault). Save the returned id.
3. Initiate an envelope — POST /api/v1/envelopes/initiate-base64 (or /initiate, /initiate-by-template). Either:
   • omit webhookId → uses the account default webhook, or
   • pass webhookId → uses that specific webhook for this envelope.
4. Receive the callback — your server gets a POST from Sadq at webhookUrl when the event fires, with the payload shown in section 8. Verify it using the Authorization header against your headerToken.
5. Troubleshoot if needed — GET /api/v1/webhooks/logs to see delivery status/errors, POST /api/v1/webhooks/recall to retry a failed delivery (using the requestId).

13. Quick reference table