Webhooks

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 check ID that has been updated, and its new status.

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

Payment Webhooks can have the following statuses:

• PAID
• UNPAID
• MAILED
• IN_PROCESS
• VOID
• EXPIRED
• PRINTED
• FAILED
• REFUNDED

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

Prefund Balance Update Notification

Using the same webhook URL, you can receieve notifications when your prefund account balance has been successfully updated.

This can be especially useful for Just In Time (JIT) funding, facilitating instant payment options.

The webhook notification has the following structure:

{
  "id": <ID of prefund bank account>,
  "amount": <amount that was added>,
  "description": <description of transactions>,  
  "balance": <new balance>,
  "user_id": <id of user associated with prefund account>,
  "type": "PREFUND_ACCOUNT"
}

❗️

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 need to 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.

❗️

Required: Whitespace in Request Body

Spaces are required in the concatenated request body. Ensure the body is JSON stringified and not trimmed or parsed to an object directly (as shown in the example below).

❗️

Required: Lowercase Signature Prefix

The 's' in the signature prefix should be lowercase. Notice all signature prefixes are lowercased in the example above.

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 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 enable you to receive a callback when a new transaction is initiated on a virtual card. See Authorize Virtual Credit Card Transactions for more information on virtual card transactions. The webhook you defined will receive a POST call from the Checkbook 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, this means that the transaction was approved. If, on the other hand, the server 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. Depending on how your integration operates, you may need to whitelist these domain names. To help your integration operate securely, the application must also verify that it is communicating with the Checkbook servers through one of Checkbook's 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 Checkbook's IP addresses (the same for Production and Sandbox).

📘

Webhooks IP addresses

52.10.180.255
54.70.79.20