Webhooks — automatic document status change notifications (API)

Instead of repeatedly polling for a document's status, have changes reported to you automatically: Signi will call an address in your application as soon as the document changes state. This is called a webhook.

How to set up a webhook

Webhooks are specified when creating a document, in the JSON instructions (only for the main document, not for attachments):

{
    "people": [ ... ],
    "file": "uploaded_file_key",
    "webhooks": [
        { "state": "completed", "url": "https://your-app.com/signi-done" },
        { "state": "rejected",  "url": "https://your-app.com/signi-rejected" }
    ]
}

The called address can be the same for all states — you'll recognize which state occurred from the state field in the incoming data.

You can be notified of transitions to the states pending, completed, rejected, and expired — see what they mean in the article Document lifecycle.

What you will receive

Signi sends a POST request to your address with information about the document:

{
    "contract_id": 1,
    "state": "completed",
    "file": "__TEMPORARYURL__",
    "attachments": [
        { "contract_id": 2, "state": "completed", "file": "__TEMPORARYURL__" }
    ]
}

• contract_id — the document ID (the same one you received when creating it).
• state — the state the document transitioned to.
• file — a temporary address for downloading the PDF; valid for 10 minutes — see Downloading a PDF from the link in a webhook.
• attachments — the same for the document's attachments.

When a webhook fails

• We retry delivery automatically. If your address does not respond (server unavailable, 5xx error), Signi will repeat the call a total of three times: the first retry after 5 seconds, the second after another 10, and the third after another 20 seconds. If even the last attempt fails, no further attempts are made; you can find out the document's status at any time by querying its detail.
• The address must be publicly reachable (HTTPS). An invalid address will return a "Webhook is invalid" error when creating the document.
• A disallowed state will return "Webhook state [state] is not allowed" — see Errors and their solutions.

Where to go next

• Document lifecycle
• Downloading a PDF from the link in a webhook
• Email notifications — email alerts to signers (instead of messages for your system)
• Quickstart — your first document for signing via API