How to enable webhook in sandbox?

A webhook sends a message to your own server when something happens in your Online Check Writer account, such as a check being updated or a payment changing status. This page shows how to turn on webhooks in the sandbox, and how to check that each message really came from us.

Quick answer: Go to Settings, then More, then Developer Panel, and open the Webhooks tab. Enter your Webhook URL and a Secret Key, set the Status to Enabled, pick your events, and click Update.

How to enable a webhook

Step 1

Open the Developer Panel

In the left menu, click SETTINGS, then More. On the More page, click Developer Panel. The sandbox page is https://sandbox.onlinecheckwriter.com/manage/developer/index.

More page with the Developer Panel card, opened from SETTINGS and More in the left menu

Step 2

Open the Webhooks tab

In the Developer Panel, click the Webhooks tab. The Webhook Settings window opens. Under it, provide the details below.

Developer Panel Webhooks tab with Webhook URL, Secret Key, Status and Events Subscription

Webhook URL: the web address on your server where we send the messages.
Secret Key: any key you choose. We use it to sign each message, so you can check that the message came from us.
Status: choose Enabled so we send the messages, or Disabled to stop them.
Events Subscription: tick the events you want to receive. The page shows how many events you have selected.

Step 3

Pick your events

The NEW view lists every event you can choose, such as check.updated, check.mailing.tracking, sendPayment.updated, and wallet.funding.ach.updated.

The OLD view is shorter. It has two choices: Mail Tracking Status and Send Check Status Update.

Webhook Settings in the OLD view with Mail Tracking Status and Send Check Status Update

Step 4

Save

Click Update to save your webhook.

Using the Classic version? Click More in the left menu, then Developer Panel, and open the Webhooks tab.

Webhook Signature Validation

To secure our webhook events, we are signing the HTTP request body with an HMAC using the secret as the signing key. Every webhook created has a secret used to sign requests with a signature header allowing listeners to validate requests. All webhook request messages are sent with a signature header key which should be used to validate the message payload. The algorithm calculates the HMAC of the HTTP request body in bytes using the webhook secret as the key (via SHA-256). If the calculated HMAC matches the value in the signature, then the message should be considered valid. If the HMAC validation fails, the message should be discarded.

In short: Your server uses the same secret key to work out the signature itself. If it matches the signature we sent, the message is real. If it does not match, throw the message away.

Code Snippet - PHP Example

PHP

1// Your secret key or token

2$secretKey = 'your_secret_key';

3// The payload and signature received from the webhook

4$payload = json_encode($payload); // Replace with the actual way you retrieve the payload

5$receivedSignature = $_SERVER['HTTP_SIGNATURE']; // Replace 'HTTP_SIGNATURE' with the actual header key signature

6

7// Calculate the expected signature

8$expectedSignature = hash_hmac('sha256', $payload, $secretKey);

9

10// Compare the received and expected signatures

11if (hash_equals($expectedSignature, $receivedSignature)) {

12    // Signature is valid, proceed to process the webhook data

13    // ...

14} else {

15    // Signature is invalid

16    // Handle the error

17}

See what we sent

The Developer Panel also has Webhook logs. Click See Webhook History to see the messages that were sent. There is also a Webhook Documentation link in the Support & Resources box.

Need more help?

For quick reference and immediate information about our API, please visit https://onlinecheckwriter.com/online-check-writer-api/.

For requests or more detailed information about our API, please send your inquiry to us at Support@onlinecheckwriter.com. Our development team will be in contact.