Articles on: For Business and Individuals

Setting Up Event Webhooks in BlueNotary

Webhooks let BlueNotary send a real-time notification to your own system whenever something happens in a session, such as a session being created, completed, or updated. Use them to keep your CRM, title software, or internal tools in sync automatically.


Available to Enterprise customers. Webhook setup is turned on for your account by BlueNotary. If you don't see the Webhooks section in Settings, or you see a "Real-Time Event Notifications" promo instead of the setup screen, see Can't find the Webhooks section? below.


Before you start

  • You need a business account administrator login (or a team member with the Admin business role).
  • Webhooks must be enabled on your account by BlueNotary.
  • Have ready the HTTPS endpoint URL on your server that will receive the events, and any authentication header your server requires (for example an API key).


Step 1: Open Webhook settings

  1. Log in to BlueNotary.
  2. Go to Settings.
  3. Scroll to the Webhooks section ("Configure webhook endpoints and event subscriptions").




Step 2: Create a webhook

  1. Click New Webhook (or Create Webhook if the list is empty).
  2. Fill in the form:

Field

What to enter

Label

A name for your own reference, e.g. "Session Events".

Method

How BlueNotary sends the request: POST (default), PUT, or PATCH.

Endpoint URL

The full URL that will receive events, e.g. https://your-server.com/webhook. Must be a valid URL.

Custom Headers

Optional. Click Add Header to add a header name and value, such as an Authorization header your server checks.

Event Subscriptions

Tick the events you want. Use Select All or Clear, or use All / Clear on each category.

Document Delivery

Appears only when you select an event that carries documents (session completed, e-sign action completed, signature certificate). Choose Full documents, Download links (secure link valid for 24 hours, keeps the payload small), or Names only.

  1. Click Create Webhook.


Your webhook appears in the list as Active, showing its method, URL, and number of subscribed events.



Step 3: Send a test event

Before relying on the webhook, confirm your server receives it.

  1. On your webhook's row, click the bug icon (Test Webhook).
  2. Choose an Event Type and adjust the sample signer, session, and document details if you like.
  3. Click Send Test Event.
  4. Check that your server received and accepted the request.


Step 4: Check delivery in Webhook Logs

Click Webhook Logs at the top of the section (or the list icon on a single webhook) to see every delivery attempt. You can filter by date range, status code, event, webhook, and session ID, and expand a row to see the full request and response. Use the logs to troubleshoot if your server returns an error.


Managing your webhooks

Each webhook row has these actions:


Action

What it does

List icon

View logs for this webhook.

Pencil icon

Edit the label, URL, headers, events, or document delivery.

Bug icon

Send a test event.

Deactivate / Activate

Pause or resume deliveries without deleting the webhook.

Trash icon

Delete the webhook permanently. This cannot be undone.



Delivery, retries, and security

Does BlueNotary retry if my server doesn't respond?

Yes. Each event is attempted up to 10 times in total (the first attempt plus up to 9 retries). Waits between attempts roughly double each time: about 5s, 10s, 20s, 40s, 80s, then 160s and 180s for the remaining retries. That is about 15 minutes of waiting in total, plus the time each attempt takes. Please note that this is subject to change in future.

  • Timeout: Your server should respond within about 15 seconds. After a timeout, the next attempt allows a longer wait (up to about 45 seconds).
  • Retried: No response or connection error, timeouts, 408, 429, and any 5xx.
  • Not retried: Other 4xx responses (for example 400, 401, 403, 404). These usually mean a wrong URL, bad credentials, or a rejected payload, so retrying wouldn't help. Fix the cause and use the logs to see what happened.
  • Success: Any 2xx response. Reply quickly and process the event afterward.
  • Deactivated webhooks: If you deactivate a webhook, pending retries stop.
  • Because of retries, your server may receive the same event more than once. Make your handler safe to run twice.


How do I verify a webhook came from BlueNotary?

Webhook payloads are not signed. Verification works through the Custom Headers you set when creating the webhook.

  1. Add a header such as Authorization: Bearer <your-secret> (or Basic ..., or a custom header like X-Api-Key).
  2. BlueNotary sends it with every delivery, and your server rejects any request that doesn't match.


Other tips:

  • Use HTTPS endpoints only.
  • Use a long, random secret and rotate it by editing the webhook.
  • Requests are sent with the User-Agent BlueNotary-Webhooks/1.0.

Can't find the Webhooks section?

Webhooks are an Enterprise feature that BlueNotary enables per account. What you see depends on your account:

  • No Webhooks section at all: Your account type doesn't include it, or you aren't signed in as an administrator.
  • A "Real-Time Event Notifications" promo instead of the setup screen: Webhooks haven't been enabled on your account yet.

In either case, please reach out to your BlueNotary account manager and ask them to enable webhooks for your account. They will confirm your plan and turn the feature on. Once it's enabled, refresh Settings and the section will appear.
If you aren't sure who your account manager is, contact BlueNotary support and we'll connect you.

Need more detail?

For payload formats, event definitions, and signature verification, see the Webhook documentation.

Updated on: 04/11/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!