Webhooks guide

Webhooks deliver near real-time updates whenever signings are sent, cancelled, or completed. Use them to keep internal dashboards in sync, trigger downstream automations, or archive completed documents without polling the API.

Typical workflow

1. Register a webhook – Define the event type(s) you care about and the target URL that should receive notifications.
2. Store the shared secret – Creation responses include a signing secret. Save it securely; you will need it to verify payloads.
3. Handle events – Expose an HTTPS endpoint that accepts POST requests, validates the signature header, and queues work for processing.
4. Monitor delivery – Log attempts and respond quickly with 2xx status codes. Krebit Sign retries on transient failures and may disable webhooks that repeatedly return errors.

Event catalog

Common events include:

Event	Value	Trigger
Signing sent	signing.sent	A draft transitions to live and invitations are dispatched.
Document completed	signing.document.completed	A document receives all required signatures.
Signing cancelled	signing.cancelled	An active signing is cancelled by an operator or automation.

Check your tenant’s event list for additional options; new events become available as the platform evolves.

Verify signatures

Webhook requests include an HMAC signature header (X-Signature) and the client identifier in X-Client-Id. The secret returned during creation is used to compute this hash.

import crypto from 'node:crypto';

function verifySignature(rawBody: Buffer, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Make sure your HTTP framework provides access to the raw request body. Parsing JSON before computing the signature may change whitespace and break validation.

Reliability best practices

• Respond quickly – Acknowledge requests with 200 as soon as you enqueue work. Process the event asynchronously to avoid timeouts.
• Handle retries – Design idempotent consumers. Store the id field included in each payload and ignore duplicates.
• Secure endpoints – Require HTTPS, restrict IP ranges if possible, and rotate webhook secrets on a schedule.
• Test first – Use tunneling tools against your tenant to validate your handler before going live.

Troubleshooting

• No payloads arriving – Confirm your endpoint is reachable from the public internet and returns 2xx responses.
• Signature mismatch – Verify you are using the latest secret and the unmodified raw body when calculating the HMAC.
• Too many retries – Log attempts and error messages. Krebit Sign may disable the webhook after repeated failures; re-enable it once your handler recovers.

When you need the exact payload structure or request fields, open the Webhooks section in the generated API reference from the sidebar.