Webhooks V1
Webhooks allow your application to be notified of changes in a transaction's state rather than requesting the state from the API directly.
Webhooks Version Migration
Version 1 of our webhooks are no longer being updated. Please refrain from using this system for new development and refer to our Webhooks V2 page for new implementation and migration details.
The POST request sent from Proof contains a JSON body that describes the event and data relevant to the event.
There are three types of events that Proof will return: transaction_status_update, user_failed_transaction, and notary. 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 and notaries in both accounts.
Request Body
| name | description | example |
|---|---|---|
| event (string) | Specifies the type of webhook event. Three events exist today: transaction_status_update, user_failed_transaction, and notary | "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"
}
}
Notary Update
{
"event": "notary",
"data": {
"id": "us_1234567",
"status": "created"
}
}
Transaction Statuses
Proof will pass back any of the following statuses, as it relates to the status of the transaction.
| Webhook Status | Description |
|---|---|
| created | Draft transaction is created in Proof |
| sent | Transaction has been sent to the signer |
| received | Signer has opened transaction in Proof |
| completed | Signer has completed signing and/or notarizing all documents |
| completed_with_rejections | The notary rejected one or more documents during the meeting; one or more documents are successfully signed |
| completed_pending_charge | Signer has completed signing but has not yet paid |
| esign_completed | (For hybrid transactions only - no notary meeting) Signer has completed esigning documents. Copies of "wet-sign" documnts (documents that will be signed on paper) have not yet been uploaded |
| wet_sign_documents_updated | (For hybrid transactions only - no notary meeting) Copies of "wet-sign" documents have been uploaded |
| recalled | (Real Estate API only) The transactions was recalled from a later state back into draft state |
| sent_to_title_agency | (Real Estate API only) A copy of the transaction has been placed in the Title Agency account; the title agent was notified that the transaction is ready for their document upload |
| sent_to_closing_ops | (Real Estate API only) The transaction has been sent to the Proof Closing Concierge team. |
| paid | The signer has paid for the transaction. |
| deleted | The transaction has been deleted; it is no longer viewable in the Proof UI. |
| expired | The signing window passed before the transaction was completed |
Notary Statuses
Proof will pass back any of the following notary statuses, as it relates to the status of notaries connected to your account.
| Webhook Status | Description |
|---|---|
| created | A BYOT notary has been added as a team member of the account |
| needs_review | The notary has completed their onboarding materials and is under review by the Proof compliance team. |
| compliant | The notary has been successfully onboarded and approved as fully compliant. |
| non_compliant | The notary was not approved as compliant. |
Errors and Retries
The webhook expects the receiver to respond with a 200 response code. If for some reason Proof cannot reach the webhook URL or your application responds with any response code other than 200, Proof 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 a back-off algorithm that will make up to 16 attempts across 48 hours.
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 Proof. 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
Retrieve 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 15 days ago