Receive session webhooks

Enable and configure an endpoint

Webhook setup requires the feature to be enabled for your account and an administrator or authorized business-admin teammate. Use the Webhooks section in Settings to configure the endpoint, event subscriptions, and document delivery.

1. Create the receiver

   Provide an HTTPS endpoint and a secret header your application verifies.

2. Choose events

   Subscribe to the smallest set your integration needs.

3. Choose document delivery

   Select files, download links, or names only for document-carrying events.

4. Test and inspect logs

   Send an authorized test event and inspect request/response delivery logs.

Authenticate the configured header

The current webhook payloads are not signed. Configure a long random secret in a custom header and verify it on your server before accepting the event.

Read the event envelope

The illustrative payload below shows a managed delivery. Correlation values may be null. Staged eSign can also include stage_position. Document array names vary by event.

{
  "event_type": "session_completed",
  "event_timestamp": "2030-01-15T15:24:00.000Z",
  "notarization_id": "order-1042",
  "bn_session_id": "67af8e4d1dfa453d2a05b24e",
  "session_reference_number": "BN-EXAMPLE",
  "delivery_id": "example-delivery-id",
  "req_id": "example-attempt-id",
  "event_details": {
    "message": "Session completed successfully.",
    "final_output_files": [
      {
        "name": "signed-agreement.pdf",
        "initial_document_name": "agreement.pdf",
        "base64Doc": "BASE64_PDF_CONTENT"
      }
    ]
  },
  "event_by_details": {
    "first_name": "Alex",
    "last_name": "Notary",
    "name": "Alex Notary",
    "email": "notary@example.com"
  }
}

Make processing safe to repeat

Acknowledge only after your receiver has durably accepted the event. Then atomically deduplicate or claim the managed delivery before applying business side effects.

1. Authenticate

   Reject a missing or incorrect configured secret.

2. Durably accept

   Store the event or enqueue it reliably, then return a 2xx response promptly.

3. Claim by delivery_id

   Use an atomic uniqueness or processing claim before side effects.

4. Process and reconcile

   Update the order, retrieve artifacts, and use GET session when state needs confirmation.

Understand delivery outcomes

The current implementation allows 10 total attempts. Retry waits and timeouts are operational policy, so avoid baking exact delay intervals into business logic.

Choose document delivery

Document links expire 24 hours after delivery in the current implementation. Persist the files you need before expiry, or use the supported retrieval API.

Recover from delayed or reordered events

Do not assume strict global event ordering. Use timestamps and resource state to avoid moving an order backward. Reconcile using GET session when the event sequence is incomplete.

• Do not deduplicate only by session ID plus event type; joins and other events can legitimately repeat.
• Allow unknown event types and additive fields without breaking your receiver.
• Keep request/attempt IDs for diagnosis, but redact secrets and access links.
• A session_completed_clicked event means processing began, not that final files are ready.

Keep building