Webhooks

Webhooks push envelope activity to your systems as it happens. They are configured per account, separately for production and sandbox, and require the Business plan or above.

Manage them at Settings → Account → Webhooks:
app.signater.com/settings/account/webhooks

Webhooks are administrator-only and are configured in the app — the integration API has no endpoints for managing them.

Creating a webhook

Field	Required	Notes
Name	Yes	Keep it under 155 characters.
Description	No
Endpoint method	No	Defaults to `POST`.
Endpoint URL	Yes	Use HTTPS; it is not enforced for you.
Events	Yes	At least one.
Authentication type	No	Defaults to `HookdeckSignature`.

Signater authenticates to your endpoint however it expects: HookdeckSignature (default), BasicAuth, ApiKey, BearerToken, OAuth2ClientCredentials, OAuth2AuthorizationCode, CustomSignature or AwsSignature.

A webhook can be deactivated and reactivated without deleting it.

Events

Envelope events

Event	Fires when
`envelope.created`	A new envelope is created.
`envelope.publish_scheduled`	Publication is scheduled for a future time.
`envelope.published`	The envelope is published and signers are invited.
`envelope.published_by_schedule`	A scheduled publication fired.
`envelope.unpublished`	The envelope is put on hold — including when the account runs out of balance and live envelopes are held automatically.
`envelope.updated`	The envelope is updated or renamed.
`envelope.cancelled`	The envelope is explicitly cancelled.
`envelope.expired`	The expiry date passed without completion.
`envelope.signed`	Every required signer completed. Also fires immediately on publish if there was nobody left to wait for.

Signer events

Event	Fires when
`envelope.viewed_by_signer`	A signer opened the envelope.
`envelope.approved_by_signer`	A signer completed their part. Under `signInOrder` this is not the end.
`envelope.rejected_by_signer`	A signer declined.
`envelope.cancelled_due_to_mfa_error_by_signer`	A signer failed identity validation and the workflow stopped.

A rejection or an MFA cancellation does not produce envelope.cancelled. Those two end the envelope through the signer events only. A state machine keyed on envelope.cancelled will wait forever.

There is no event for moving, trashing, restoring or changing the owner of an envelope, nor for individual field confirmations.

Payload

Envelope events:

{
  "event_type": "envelope.created",
  "envelope_id": "696d0b7f-8e2f-4fb1-9605-72b197ee154d",
  "account_id": "00cae3c2-8b7c-41b6-b934-6724808fe7f7",
  "env": "production"
}

Signer events add signer_id:

{
  "event_type": "envelope.approved_by_signer",
  "envelope_id": "696d0b7f-8e2f-4fb1-9605-72b197ee154d",
  "signer_id": "5241f81e-e7e2-447a-8534-ee08931260ae",
  "account_id": "00cae3c2-8b7c-41b6-b934-6724808fe7f7",
  "env": "production"
}

env is production or sandbox. There are no other fields.

The payload carries identifiers, not state, on purpose. Fetch the envelope from the API when an event arrives: that is current, whereas an event describes one moment.

Delivery

Order is not guaranteed. Events are drained in concurrent batches, so they can overtake each other. Do not infer state from arrival order.

Expect duplicates. Delivery is retried automatically by our delivery layer, and a retry can arrive after your endpoint succeeded but answered too slowly. Key your handlers on envelope_id plus event_type and make them idempotent.

Answer quickly. Acknowledge with a 2xx as soon as you have the payload and process it asynchronously. Slow endpoints are treated as failures.

Delivery stops silently if the account drops below the Business plan, is deactivated, or — for sandbox — has sandbox switched off. Events are discarded, not queued. If your endpoint goes quiet, check the plan before you check your code.

Request headers

Every delivery carries:

Content-Type: application/json; charset=utf-8
X-Signater-ApiKey: <32 hex characters>

X-Signater-ApiKey is generated once per account and identifies the account the event belongs to. It is the same value for production and sandbox and it is not rotated. It is not currently surfaced in the app — if you want to verify it, ask support for your account's value, or rely on the authentication method you configured on the webhook, which is the stronger option.

Local debugging with the CLI

You can forward live events to a service on your machine without touching your registered webhooks.

Install the Hookdeck CLI

Linux: download the latest release, tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz, then run ./hookdeck. Full instructions in the Hookdeck CLI documentation.

Connect it

Open the webhooks page for the environment you want — production and sandbox are configured separately.

Click the button next to Create Webhook.

Choose CLI Settings, paste the URL the CLI gave you, and switch the integration on.

Forwarding is additive: your registered endpoints keep receiving events while the CLI is connected. The CLI integration switches itself off after 2 hours unless you turn it off sooner.

Creating a webhook#

Events#

Payload#

Delivery#