Questions? Feedback? powered by Olark live chat software

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 at https://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
}

Note

Escrow.com has a 10 second timeout on your webhook requests. Webhooks will not be retried if the request fails.

Webhook events

This table shows the possible events that trigger webhooks.

event_typeeventdescription
transactioncreateA new transaction has been created.
transactionagreeAll parties have agreed to the transaction.
transactionparty_verification_submittedA party has submitted their verification for review.
transactionparty_verification_approvedA party has had their verification reviewed and approved.
transactionparty_verification_rejectedA party has had their verification reviewed and rejected.
transactionpayment_approvedEscrow.com has approved the payment for the transaction and the goods may now be shipped by the seller.
transactionpayment_rejectedEscrow.com has rejected the payment for the transaction.
transactionpayment_sentThe buyer has sent payment to Escrow.com.
transactionpayment_receivedEscrow.com has received payment from the buyer.
transactionpayment_refundedEscrow.com has refunded a buyer's payment.
transactionpayment_disbursedEscrow.com has disbursed payment to the seller.
transactionpayment_rejectedEscrow.com has rejected the payment for the transaction.
transactionshipThe seller has indicated that the goods have been shipped.
transactionreceiveThe buyer has indicated that the goods have been received.
transactionacceptThe buyer has indicated that the goods have been accepted.
transactionrejectThe buyer has indicated that the goods have been rejected.
transactionship_returnThe buyer has indicated that the goods to be returned following rejection have been shipped.
transactionreceive_returnThe seller has indicated that the goods to be returned following rejection have been received.
transactionaccept_returnThe seller has indicated that the goods to be returned following rejection have been accepted.
transactionreject_returnThe seller has indicated that the goods to be returned following rejection have been rejected.
transactioncompleteAll disbursements have been made to the seller, closing statements have been sent. Escrow.com marked the transaction as complete.
transactioncancelEscrow.com has marked the payment as cancelled.
transactionoffer_acceptedThis is sent for Escrow Offer transactions, when an offer has been accepted.
transactionrefund_resolvedThis is sent when Escrow.com has approved to process a refund for a transaction.
transactionrefund_rejectedThis is sent when Escrow.com has rejected to process a refund for the transaction.