Documentation | Checkbook

Status Update Notification

If you would like to receive notifications when the status of a check has been updated, you can specify a webhooks url in your developer settings. When the status of a check is updated, you will receive a POST request to the specified url containing the id of the check that has been updated and its new status.

All of the webhooks notifications are signed with your unique webhooks key (from your developer settings) allowing you to verify that the request was sent from Checkbook.io and was not tampered with.

{ 'status': <check status>, 'id': <check id>, 'type': "CHECK" | "INVOICE" }

❗️

Webhooks key by environment

The webhooks key is different in each environment. You need to use your Sandbox key in the Sandbox environment and your Production key in the Production environment.

Signature

Each webhooks POST request comes with an additional Signature field, which can be found in the HTTP headers. The signature will look something like:

Signature: nonce=1243549809,signature=4ee9758fc0bceb3ca1a2fe397fbd125364cfffdb04296fa118dab9778a4b3ce3

In order to verify the signature, you will concatenate the request body (the string value of the JSON payload) with the nonce value (i.e. 1243549809 in the above example). You will then compute a HMAC with the SHA256 hash function, where your webhooks key is the signing key, and the request body + nonce string is your message. The output of this HMAC should match the value of the signature field.

Example

For example, the signature in the example above (i.e. 4ee9758fc0bceb3ca1a2fe397 fbd125364cfffdb04296fa118dab9778a4b3ce3 ) is computed from the following values:

body: '{"status": "PAID", "id": "ed0af5fb335c47dd8eb53199ba50f5c4", "type": "CHECK"}' nonce: 1243549809 webhooks key: '335b5728e25b47e88995fce207bff380'

Virtual Credit Card Notification

We offer you the possibilty to allow / deny specific transactions for a virtual card in real time. You need to set a webhook for "Virtual Cards URL" in the Developer Settings, which will allow you to receive a callback when a new transaction is initiated on a virtual card. See Authorize Virtual Credit Card Transactions for more info. The webhook you defined will receive a POST call from our servers with a payload containing the following values:

{ "amount": "the transaction amount", "user_id": "id of the user associated with the virtual card", "account_id": "virtual card id", "recipient": "merchant description" }

If the status code of the webhook response is 2XX, then it is considered that you approved the transaction. If not, the transaction is denied. For example, if your server responds with a 200 status code to the webhook request, then it means the transaction was approved. If on the other hand it responds with a 400 status code, then the transaction was denied.

IP White List

Your application must be able to reach Checkbook's domain names for it to function properly and depending on how your integration operates, you may need to whitelist them. To help your integration operate securely, it must also verify that it’s communicating with our servers through one of our IP addresses listed below.

📘

Production (api.checkbook.io)

99.83.192.53
75.2.12.84

📘

Sandbox (api.sandbox.checkbook.io)

76.223.87.18
13.248.217.122

If your integration also receives webhooks from Checkbook, you should ensure these events originate from one of our IP addresses (the same for Production and Sandbox).

📘

Webhooks IP addresses

52.10.180.255
54.70.79.20