Webhooks

Integrate your application with Signa lifecycle events. Webhooks notify your system when forms are viewed, submissions are completed, templates change, or delivery workflows need attention.

Registering webhooks

Create a webhook URL from Settings > Webhooks. Pick the events your integration needs, save the URL, and copy the HMAC secret for request verification.

Consuming webhooks

Inspect the event type, verify the HMAC signature, then process the payload. Signa stores response status, response body, errors, retries, and manual resend attempts for production debugging.

Example webhook payload

{
  "id": "evt_01h9w8d7e6",
  "type": "submission.completed",
  "payload": {
    "id": "36",
    "template_id": "12",
    "submitters": [
      {
        "email": "client@example.com",
        "status": "completed"
      }
    ]
  }
}

See all event types

Delivery and retries

Webhooks are delivered from the queue so the signer experience is not blocked by your endpoint. Treat every webhook as at-least-once delivery: persist the event id, make processing idempotent, and return a 2xx response only after your application has safely accepted the payload.

Use event.id as your idempotency key.

Store raw request bodies until HMAC verification completes.

Inspect delivery attempts, response codes, response bodies, and stored errors from Signa activity logs.

Event types

form.viewed
Fired when the form viewed lifecycle transition occurs.
form.started
Fired when the form started lifecycle transition occurs.
form.completed
Fired when the form completed lifecycle transition occurs.
form.declined
Fired when the form declined lifecycle transition occurs.
submission.created
Fired when the submission created lifecycle transition occurs.
submission.completed
Fired when the submission completed lifecycle transition occurs.
submission.expired
Fired when the submission expired lifecycle transition occurs.
submission.archived
Fired when the submission archived lifecycle transition occurs.
template.created
Fired when the template created lifecycle transition occurs.
template.updated
Fired when the template updated lifecycle transition occurs.
template.archived
Fired when the template archived lifecycle transition occurs.

Verify a request

import crypto from "node:crypto";

const signature = request.headers["x-signa-signature"];
const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(rawBody)
  .digest("hex");

if (signature !== expected) {
  throw new Error("Webhook signature mismatch");
}

Security

Every webhook includes a signature header generated from the raw request payload and the webhook secret. Compare signatures before trusting the payload, and rotate secrets from the webhook settings page when needed.

Local endpoint test

curl https://your-app.example.com/webhooks/signa \
  -H "Content-Type: application/json" \
  -H "x-signa-signature: {computed_hmac}" \
  -d '{"id":"evt_test","type":"submission.completed","payload":{"id":"36"}}'

Production checklist

Use HTTPS with a publicly reachable endpoint.
Verify x-signa-signature against the raw request body.
Reject unverified payloads before parsing business data.
Persist event ids and make handlers idempotent.
Return quickly and move expensive work to your own queue.
Use submission metadata/external_id to map events back to your records.