Webhooks

Webhooks provide a powerful way for your application to receive real-time updates about events happening within your Checkbook account, without the need for constant polling of our API. Instead of your application repeatedly asking for information, Checkbook will automatically send HTTP POST requests to a URL you configure whenever specific events occur.

By leveraging Checkbook webhooks, you can build more efficient, real-time integrations that react instantly to important events within your payment ecosystem.

How Webhooks Work

Configuration

You can configure your webhook URL within the developer settings  section of your Checkbook dashboard. You will need to provide:

Webhook URL: The public URL where you want to receive webhook events. Ensure these URLs are HTTPS endpoints and are accessible by Checkbook’s servers.

Security

Checkbook provides a signature to help you verify the authenticity of incoming webhook requests via a SHA-256 hash-based message authentication code. This signature can be found in the signature HTTP header of each request and contains a signature generated by Checkbook using a secret key associated with your account.

Signature Verification

You should verify this signature on your server to ensure that the webhook request originated from Checkbook and has not been tampered with during transit. To correctly verify the signature:

Retrieve the signing key

This key can be found on the developer settings  page of the dashboard. The signing key is tied to your account and does not change when API keys are generated or revoked. A signing key will be a collection of letters and numbers and will look something like:

335b5728e25b582e88995fce207bff380

Prepare the payload

Prepare the signed payload by extracting the body and headers from the webhook response. The Signature HTTP header contains a nonce field that must be extracted. The prepared payload should look like: webhook body + nonce

POST https://dundermifflin.com/webhook/checkbook
Content-Type: application/json
signature: nonce=1243549809,signature=48a3e4bfd23c405c24387907933c28a8713f847bccd62109178f55045511efcb
 
{ "id": "de7ef9b5ed7945368cd9d5c84c13d86b" }

In the example above, the prepared payload will look like:

1243549809{ "id": "de7ef9b5ed7945368cd9d5c84c13d86b" }

Generate a signature

Generate a signature using the HMAC-SHA256 algorithm, using your webhook signing key as the key, and the payload prepared above as the message.

import hmac
import hashlib
 
webhook_key = '335b5728e25b582e88995fce207bff380'
payload = '1243549809{ "id": "de7ef9b5ed7945368cd9d5c84c13d86b" }'
signature = hmac.new(webhook_key.encode(),
                     payload.encode(),
                     hashlib.sha256).hexdigest()

$webhookKey = '335b5728e25b582e88995fce207bff380';
$payload = '1243549809{ "id": "de7ef9b5ed7945368cd9d5c84c13d86b" }';
$signature = hash_hmac('sha256', $payload, $webhookKey);

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
)
 
payload := "1243549809{ \"id\": \"de7ef9b5ed7945368cd9d5c84c13d86b\" }"
webhookKey :=  []byte("335b5728e25b582e88995fce207bff380")
h := hmac.New(sha256.New, webhookKey)
h.Write([]byte(payload))
signature := hex.EncodeToString(h.Sum(nil))

Compare the hash

Compare the generated hash with the signature value in the signature header. If they match, the request is authentic.

Error Handling and Retries

If your webhook endpoint returns a non-2xx status code or does not return within 10 seconds, Checkbook will attempt to resend the webhook event after a delay. The first attempt will come 30 seconds after the initial request, and each subsequent request will follow the rules of exponential backoff — the second after 1 minute, the third after 2 minutes, etc. However, Checkbook will only retry a webhook for a maximum of 11 attempts. It’s crucial to ensure your webhook endpoints are reliable and can handle potential errors gracefully.

Supported Events

Checkbook supports notifications for various events. The specific events available may evolve over time, so check back with this page for a comprehensive and up-to-date list.

 
{
  "status": "IN_PROCESS",
  "id": "8b0ececd521c425db52cddf8d6930d54",  
  "type": "CHECK",
  "deposit_option": "ACH"
}

{
  "status": "PAID",
  "id": "438fd2d78d7b4b579d6d0968633768f3",  
  "type": "INVOICE"
}

{
  "status": "VERIFIED",
  "id": "1bc0ce5ce7cf447ca9f2dad1ee2a98ce",  
  "type": "ACCOUNT",
  "user_id": "bb100683cfa34ed9a17e42de91e1ea28"
}

{
  "status": "VERIFIED",
  "amount": 500.00,
  "balance": 1852.23,
  "id": "5b7946d45a7a4c7eb457cb7fe05250b3",  
  "type": "PREFUND_ACCOUNT",
  "user_id": "bb100683cfa34ed9a17e42de91e1ea28",
  "description": "Dinner party Dundie Award refund"
}