Webhooks

Webhooks let your app react to document lifecycle events the moment they happen — no polling required. Signus POSTs a signed JSON payload to a URL you control whenever an event you’ve subscribed to fires.

Create a webhook

Webhooks are managed from the Signus app, not the public API.

Open Settings → Developer → Configuration

Navigate to Settings → Developer and scroll to the Webhooks section.

This area is Organization Admin only and requires API access to be enabled on your workspace.

Click “Create webhook”

A dialog opens with three fields:

Endpoint URL (required) — where the POSTs go. Must be a valid HTTPS URL. Non-HTTPS URLs are rejected. Example: https://example.com/webhooks/signus.
Description (optional) — free-text label, e.g. Production notifications.
Event types (required, at least one) — checkboxes for each event you want to receive. A Select all toggle is available.

Submit

The endpoint appears in the list below with a green Active badge and a freshly generated signing secret.

Event types

Seven event types are available today:

Code	Fires when
`DOCUMENT_CREATED`	A new document is created in the workspace.
`DOCUMENT_SENT`	A document is sent to recipients.
`DOCUMENT_SIGNED`	A recipient signs a document.
`DOCUMENT_COMPLETED`	All required recipients have signed.
`DOCUMENT_DECLINED`	A recipient declines to sign.
`DOCUMENT_VOIDED`	A document is manually voided.
`DOCUMENT_EXPIRED`	A document passes its expiration date unsigned.

Subscribe to as few or as many as you need. You can change the subscription list at any time — see Edit subscriptions below.

The signing secret

Every webhook endpoint has a unique signing secret used to sign outgoing payloads, so you can verify that a request genuinely came from Signus (and not an attacker who guessed your URL).

To retrieve it:

Find the webhook row in the Webhooks section.
Click the eye icon next to the masked secret to reveal it.
Click the copy icon to copy it to your clipboard.

Store the secret alongside your API key — both should live in your secret manager.

Unlike API key secrets, signing secrets can be re-fetched from the UI at any time, but treat them as write-once anyway — they’re sensitive.

Verifying signatures

Signus uses Svix for webhook delivery, so the signature scheme matches Svix’s spec. Incoming requests include these headers:

svix-id — unique message ID
svix-timestamp — epoch seconds
svix-signature — v1,<base64-hmac-sha256> (space-separated if multiple)

The canonical verification flow:


import { Webhook } from 'svix';
 
const wh = new Webhook(process.env.SIGNUS_WEBHOOK_SECRET!);
 
// In your HTTP handler:
try {
  const event = wh.verify(rawBody, {
    'svix-id': req.headers['svix-id'],
    'svix-timestamp': req.headers['svix-timestamp'],
    'svix-signature': req.headers['svix-signature'],
  });
  // event is the parsed, verified payload
} catch (err) {
  // invalid signature — drop the request
  res.status(401).end();
}

Equivalent packages exist for Python, Go, Ruby, Rust, and more — see the Svix receiving docs .

Test a webhook

Each row has a flask icon (test-fire button). Clicking it sends a synthetic event to your endpoint and displays the result inline:

HTTP status returned by your endpoint (green for 2xx, red otherwise)
Response time in milliseconds
Endpoint response body (truncated, scrollable)

Use this to confirm your handler is reachable before going live.

Edit subscriptions

Each row has a bell icon labelled “Subscriptions”. Clicking it expands an inline editor with checkboxes for every event type, a Select all toggle, and Cancel / Save buttons. Changes take effect immediately on save.

Delete

The trash icon on each row opens a confirmation dialog. Deletion is immediate — events stop being delivered to that endpoint right away, and pending retries are dropped.

Advanced management — the Webhook Portal

For deeper operational control, switch to the Webhook Portal sub-tab on the Developer page. It embeds the full Svix management portal, giving you:

Per-delivery logs for every attempt (status code, response time, response body).
Manual retries of failed deliveries.
Replay — re-send a historical event to your endpoint.
Ingestion filtering and advanced transformation rules.

This is the right tool when you’re debugging why a specific event didn’t arrive, or when you need to replay a batch after a deploy.