Webhooks

Webhooks push events to an HTTPS endpoint you control the moment something happens, so you don't have to poll for status. This is the intended way to track envelopes through to completion.

Endpoints are managed in the app under Settings → Webhooks (owner or admin), or programmatically through the /v1/webhooks API — which is what iPaaS connectors (Zapier, Make) use to register their instant triggers.

1. Register an endpoint

Provide an HTTPS URL, pick the events you want (or leave it empty for everything your plan allows), and optionally set a shared secret plus the header it should arrive in.

You're shown a signing secret exactly once. Store it — it can't be retrieved again, only rotated.

2. Verify ownership

A new endpoint starts as pending_verification and receives no events at all until it proves it belongs to you. We POST a webhook.verification event:

{
  "event_id": "018f2c3d-…",
  "event": "webhook.verification",
  "occurred_at": "2026-07-22T10:00:00.000Z",
  "company_id": "018f0a1b-…",
  "data": { "challenge": "3f9a…", "instructions": "…" }
}

Respond 200 echoing the challenge, either as the raw body or as JSON:

{ "challenge": "3f9a…" }

The endpoint then becomes active.

3. Verify each request is really from us

Two independent mechanisms. Prefer the signature; the shared secret is the quick option.

Signature (recommended)

Every request carries these headers:

X-BunnyDoc-Signature: t=1800000000,v1=5257a869e7…
X-BunnyDoc-Event: envelope.completed
X-BunnyDoc-Delivery: 018f…
X-BunnyDoc-Timestamp: 1800000000

v1 is HMAC-SHA256(signing_secret, "<t>.<raw request body>"), hex-encoded.

const crypto = require('crypto');

function verify(rawBody, header, signingSecret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  // Constant-time compare, and reject stale timestamps to block replays.
  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  return Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) <= toleranceSeconds;
}

Shared secret (quick)

If you set one, it arrives verbatim in your chosen header (default X-Webhook-Secret). Compare it to your stored value. It travels on every request, so prefer the signature where you can — the signature never puts a key on the wire and also proves the payload wasn't altered or replayed.

4. Payload envelope

Every event has the same outer shape; only data differs.

{
  "event_id": "018f2c3d-…",
  "event": "envelope.completed",
  "occurred_at": "2026-07-22T10:00:00.000Z",
  "company_id": "018f0a1b-…",
  "data": { "envelope_id": "018f…", "title": "MSA — Acme Corp" }
}

5. Delivery semantics

• At-least-once. You may receive the same event twice. Dedupe on event_id.
• Unordered. envelope.completed can arrive before envelope.signer_signed. Order by occurred_at, not by arrival.
• Respond fast. Return 2xx within 10 seconds; queue your own work rather than doing it inline. We do not follow redirects — point the endpoint at its final URL.
• Retries. Any 5xx, 408, 429, timeout, or network error is retried at 1m → 5m → 30m → 2h → 6h (5 attempts). Other 4xx are not retried — they mean the request reached you and was rejected.
• Auto-disable. After 20 consecutive failures the endpoint is disabled and the account owner is emailed. Re-enable it in Settings.
• Delivery log is kept for 7 days — successes and failures. After that a delivery can't be inspected or replayed.

6. E-Signing events

Which events you can receive depends on your plan's tier. Advanced includes everything in standard.

Standard — envelope lifecycle

Advanced — data, documents, payments, bulk send, forms

Lifecycle payloads

Every lifecycle event carries the envelope's id and title. The ones triggered by a specific person — envelope.viewed, envelope.signer_signed, envelope.declined — add that recipient, when we know who they are.

{
  "event_id": "018f2c3d-…",
  "event": "envelope.declined",
  "occurred_at": "2026-07-22T10:00:00.000Z",
  "company_id": "018f0a1b-…",
  "data": {
    "envelope_id": "018f…",
    "title": "MSA — Acme Corp",
    "recipient_id": "018f…",
    "recipient_name": "Jane Doe",
    "recipient_email": "jane@acme.com"
  }
}

A decline is terminal for the whole envelope — nobody else can sign it afterwards, and no envelope.completed or envelope.document_ready will follow. To act on it you need the recipient, which is why they're on the payload; the reason they typed is recorded on the audit trail, not the event.

envelope.voided is sender-initiated, so there is no recipient on it:

{
  "event": "envelope.voided",
  "data": { "envelope_id": "018f…", "title": "MSA — Acme Corp" }
}

Treat envelope.declined and envelope.voided as the two ways an envelope can end without a signed document. If you're waiting on an envelope, subscribe to both alongside envelope.completed — otherwise a declined or voided envelope simply goes quiet on you.

envelope.field_values — what's included

{
  "event": "envelope.field_values",
  "data": {
    "envelope_id": "018f…",
    "title": "MSA — Acme Corp",
    "completed_at": "2026-07-22T10:00:00.000Z",
    "fields": [
      {
        "field_id": "018f…",
        "type": "text",
        "label": "Company name",
        "value": "Acme Ltd",
        "filled": true,
        "recipient": { "id": "018f…", "role": "Client", "name": "Jane Doe", "email": "jane@acme.com" }
      }
    ]
  }
}

Always excluded:

• signature and initials — captured marks, not data. (date_signed and date are included.)
• Masked fields — omitted entirely, not redacted. They're encrypted at rest, so sensitive values never leave the platform.
• Layout-only blocks (text_block, image_block, divider).

Unfilled fields appear with "value": null and "filled": false, so you can tell "asked but unanswered" from "not asked".

7. Get the completed file by URL — envelope.document_ready

This is the event that hands you the finished document. It fires once the merged, stamped and AATL-signed file actually exists, and its payload carries a time-limited CDN download URL — so you can archive a signed PDF without a second authenticated round trip.

{
  "event_id": "018f2c3d-…",
  "event": "envelope.document_ready",
  "occurred_at": "2026-07-22T10:00:00.000Z",
  "company_id": "018f0a1b-…",
  "data": {
    "envelope_id": "018f…",
    "title": "MSA — Acme Corp",
    "completed_at": "2026-07-22T10:00:00.000Z",
    "document": {
      "filename": "MSA_Acme_Corp.pdf",
      "content_type": "application/pdf",
      "size_bytes": 284119,
      "aatl_signed": true,
      "download_url": "https://cdn.bunnydoc.com/…?Expires=…&Signature=…",
      "expires_at": "2026-07-23T10:00:00.000Z"
    }
  }
}

The 24-hour clock starts when we build the event, not when you receive it. That covers the full retry window with room to spare, but a replay from the delivery log days later will contain a dead link. If expires_at has passed, don't retry the URL — fetch the document through the authenticated API instead.

Two more things that surprise people:

• Individual envelopes only. Envelopes sent as part of a bulk send do not fire this — you'd get one per recipient. Subscribe to bulk_send.download_ready for batches.
• Once per envelope. Unlike every other event, this one is de-duplicated on our side, so a retried internal job won't re-publish it. (Your endpoint can still see the same delivery twice from an HTTP retry — keep deduping on event_id.)

8. Manage subscriptions over the API

Instead of the app, an integration can manage its own endpoints with an API key. This is what powers iPaaS connectors (Zapier, Make) as instant triggers.

Both routes need webhooks in your plan, plus the matching scope on the key.

curl -X POST "https://api2.bunnydoc.com/v1/webhooks" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "target_url": "https://example.com/hooks/bunnydoc",
        "events": ["envelope.document_ready", "envelope.declined", "envelope.voided"]
      }'

{
  "id": "018f…",
  "url": "https://example.com/hooks/bunnydoc",
  "events": ["envelope.document_ready", "envelope.declined", "envelope.voided"],
  "status": "pending_verification",
  "created_at": "2026-07-22T10:00:00.000Z",
  "signing_secret": "whsec_…"
}

signing_secret is returned only on this create call — store it now. Everything else (payload shape, signature verification, retries, auto-disable) is exactly as described above: a subscription created here is an ordinary endpoint.

An empty events array means "everything my plan allows" — except envelope.document_ready, which you must name explicitly (see §7).