Notarize

Webhooks

Webhooks allow your application to be notified of changes in a transaction's state rather than requesting the state from the API directly.

The POST request sent from Notarize contains a JSON body that describes the event and data relevant to the event.

There are two types of events that Notarize will return: transaction_status_update and user_failed_transaction. user_failed_transaction is only passed back when a signer has failed to pass the knowledge based authentication (KBA) questions.

Note that webhooks are shared between Business and Real Estate APIs. This means that if you have a Business account and a Real Estate account, you can set one webhook URL and you will receive status updates for transactions in both accounts.

Request Body

namedescriptionexample
event
(string)
Specifies the type of webhook event. Two events exist today: transaction_status_update and user_failed_transaction"event": "transaction_status_update"
data
(object)
Data for this event type. Returns transaction ID and either status or details.{
"event": "transaction_status_update",
"data": {
"transaction_id": "ot_wd3y67d",
"status": "received"
}
}

Examples:

Status Update

{
  "event": "transaction_status_update",
  "data": {
    "transaction_id": "ot_wd3y67d",
    "status": "received"
  }
}

Failed Transaction

{
  "event": "user_failed_transaction",
  "data": {
    "transaction_id": "ot_ny695pd",
    "details": "User Exceeded Authentication Attempts"
  }
}

Webhook Statuses

Notarize will pass back any of the follow statuses, as it relates to the status of the transaction.

created
sent
received
completed
completed_with_rejections
completed_pending_charge
deleted
clear_to_close (Real Estate only)

Errors and Retries

The webhook expects the receiver to respond with a 200 response code. If for some reason Notarize cannot reach the webhook URL or your application responds with any response code other than 200, Notarize will retry to make the request with an exponential backoff.

Exponential Back Off

We recommend an idempotent webhook implementation. Our webhooks have a 30 second timeout - should we not receive a response in 30 seconds, we will retry the response. Requests that are retried for any reason use an exponential back-off algorithm that will make up to 9 attempts. This means we will attempt to request your webhook URL up to 9 times across roughly one day.

Note that webhooks can be sent more than once and delivery is not guaranteed to be in order. The expected behavior is for your application to manage the state and skip to the latest status.

Security

Webhook messages are signed so your application can verify that the sender is Notarize. Webhook requests contain an X-Notarize-Signature header with a hexadecimal HMAC signature of the request body, using your API key as the key and SHA256 as the hash function.

You can verify the authenticity of the webhook by computing the signature with your API key and request body, and comparing it to the value in the X-Notarize-Signature header.

Setting/Updating/Retrieving Your Webhook URL

Business API

Set/update your URL

Real Estate API

Set/update your URL
Retrieve your URL

As mentioned above, if you have a Business account and a Real Estate account, you only need to set up the webhook once and to receive status updates on transactions in both accounts.

Updated 11 months ago

Webhooks


Webhooks allow your application to be notified of changes in a transaction's state rather than requesting the state from the API directly.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.