Webhooks — automatic notifications of document status changes

Instead of repeatedly polling for a document's status, have changes reported automatically: Signi calls 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://vase-aplikace.cz/signi-hotovo" },
        { "state": "rejected",  "url": "https://vase-aplikace.cz/signi-odmitnuto" }
    ]
}

The called address can be the same for all states — you can tell 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'll 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 URL for downloading the PDF; valid for 10 minutes — see Downloading a PDF from a webhook link.
• attachments — the same information for the document's attachments.

When a webhook fails

• We retry delivery automatically. If your address does not respond (server unavailable, 5xx error), Signi retries 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 always check the document's status by querying its detail.
• The address must be publicly reachable (HTTPS). An invalid address returns the error "Webhook is invalid" when creating the document.
• A disallowed state returns "Webhook state [state] is not allowed" — see Errors and their solutions.

Where to go next

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