API Guide :: Webhooks

Using webhooks

By providing a HTTP endpoint that accepts POST requests, Escrow.com will send you updates via webhook at key points during a transaction.

Please note that Escrow.com strongly recommends verifying any data received via webhook by fetching related data such as by using the fetch transaction endpoint before taking actions based on webhook updates to ensure that the update was sent from Escrow.com.

Adding a webhook

You can add a webhook by making a POST request with your own URL you would like to be called, as such.

1
2
3
4
5
6
7
8
curl "https://api.escrow.com/2017-09-01/customer/me/webhook" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "url": "https://chrispwill.com/my-escrow-webhook"
}'

The response body will include a unique ID for the created webhook. You can use this ID to delete the webhook in future.

Example Response

1
2
3
4
{
    "id": 1234,
    "url": "https://chrispwill.com/my-escrow-webhook"
}

Getting current webhooks

To see all of the webhooks you have created, can make a GET request to the same resource athttps://api.escrow.com/2017-09-01/customer/me/webhook

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "webhooks": [
      {
        "id": 1234,
        "url": "https://chrispwill.com/my-escrow-webhook"
      },
      {
        "id": 1235,
        "url": "https://escrow-webhook.com/my-escrow-webhook"
      },
      {
        "id": 1236,
        "url": "https://sample.escrow.com/sample.escrow-webhook"
      }
    ]
}

Deleting a webhook

To delete a webhook, make a DELETE request to the webhook resource, using the unique webhook ID found by using the above GET endpoints.https://api.escrow.com/2017-09-01/customer/me/webhook

1
2
3
4
curl "https://api.escrow.com/2017-09-01/customer/me/webhook/1234" \
    -X DELETE \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \

This will return a 204 status code on successful deletion. Deleted webhooks will no longer be called.

Webhook behaviour

When transactions change state, Escrow.com will make POST requests to all of your active webhooks. The body of the POST request that we will send is as shown:

Example Webhook Call

1
2
3
4
5
{
    "event": "payment_approved",
    "event_type": "transaction",
    "transaction_id": 12345
}

Webhook events

This table shows the possible events that trigger webhooks.