Guide: How to Subscribe to Webhooks and Get Status Updates for Your Mailed Checks
Welcome! This comprehensive guide will walk you through the complete workflow of setting up webhooks to automatically receive real-time status updates when your mailed checks are created, printed, mailed, and delivered. You'll learn how to configure webhooks in the Developer Panel and track your checks from creation to delivery.
Prerequisites: Developer Panel Setup
Before making any API requests, you need to complete two essential setup tasks in the Developer Panel.
Task 1: Get Your API Key
Navigate to the Developer Panel and locate your API Key:
- Go to Sandbox Developer Panel
- Click on the "API Settings" tab
- Your API Key will be displayed (hidden with dots for security)
- Click the eye icon to reveal it, or click the copy icon to copy it directly
- Save this key securely - you'll need it for every API request
Security Warning: Keep your API key secure and never share it publicly. If you generate a new API key, your current key will be automatically revoked.
Set up webhooks to receive automatic status updates:
- In the Developer Panel, click on the "Webhooks" tab
Fill in the webhook configuration:
- Click "Update" to save your webhook configuration
Testing Tip: Use free webhook testing services like
Webhook.site to instantly create a webhook URL and view incoming webhook payloads in real-time without setting up your own server.
The Mandatory Connection Headers
For every API request in this guide, you must include these 3 headers:
- Content-Type:
application/json - Accept:
application/json - Authorization:
Bearer YOUR_API_KEY (Replace with your actual API key from the Developer Panel)
Step 1: Find Your Bank Account ID
Every check must be associated with a bank account. This request retrieves all your bank accounts and their unique identifiers.
ENDPOINT (GET)
QUERY PARAMETERS (OPTIONAL)
- perPage - Number of records per page (default: 10)
- page - Page number for pagination (default: 1)
- term - Search keyword to filter bank accounts
RESPONSE EXAMPLE
{
"success": true,
"data": {
"bankAccounts": [
{
"bankAccountId": "O7rWQ8Gpny7NjD0ZzpM",
"name": "AB COMPANY API Updated",
"accountNumber": "123456789",
"routingNumber": "021000021",
"bankName": "Chase Bank",
"isVerified": true
}
],
"pagination": {
"currentPage": 1,
"perPage": 10,
"totalRecords": 1
}
}
}
Action: Copy the bankAccountId value. You'll need this for creating checks.
Step 2: Find Your Payee ID
A payee represents the person or company receiving the check. This endpoint retrieves all your saved payees.
ENDPOINT (GET)
QUERY PARAMETERS (OPTIONAL)
- perPage - Number of records per page (default: 10)
- page - Page number for pagination (default: 1)
- term - Search keyword to filter payees
RESPONSE EXAMPLE
{
"success": true,
"data": {
"payees": [
{
"
payeeId": "
bz3Aj3ZyJ9eVw6E",
"name": "John Myresaa",
"email": "
john@example.com",
"address": "123 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001"
}
],
"pagination": {
"currentPage": 1,
"perPage": 10,
"totalRecords": 1
}
}
}
Action: Copy the payeeId for the recipient of your check.
Step 3: Create a Check
Now create the check record with all necessary details. This check will be stored in the system and ready for mailing.
ENDPOINT (POST)
REQUEST BODY (JSON)
{
"checks": [
{
"bankAccountId": "O7rWQ8Gpny7NjD0ZzpM",
"payeeId": "bz3Aj3ZyJ9eVw6E",
"amount": 100.00,
"serialNumber": "91001",
"issueDate": "2026-01-21",
"memo": "First, Test check using API for Webhooks",
"note": "Internal reference only",
"accountNumber": "1458756",
"invoiceNumber": "12545",
"categoryId": null,
"noSign": 0,
"noAmount": 0,
"noDate": 0,
"noPayee": 0,
"customElements": {
"element1": "first class tracking",
"element2": "test sender"
}
}
]
}
REQUIRED FIELDS
- bankAccountId - The ID from Step 1
- payeeId - The ID from Step 2
- amount - Check amount (decimal format)
OPTIONAL FIELDS
- serialNumber - Custom check number
- issueDate - Check date (YYYY-MM-DD format)
- memo - Memo line text
- note - Internal note (not printed on check)
- accountNumber - Account reference number
- invoiceNumber - Invoice reference
- categoryId - Category for organization
- customElements - Additional custom fields
RESPONSE EXAMPLE
{
"success": true,
"message": "Successfully created",
"data": {
"checks": [
{
"checkId": "1ZoVelMa5Mj8pwb",
"serialNumber": "91001",
"amount": "100.00",
"amountInWord": " one hundred ",
"date": "01/21/26",
"status": 0,
"memo": "First, Test check using API for Webhooks",
"bankAccount": {
"bankAccountId": "O7rWQ8Gpny7NjD0ZzpM",
"name": "AB COMPANY API Updated"
},
"payee": {
"payeeId": "bz3Aj3ZyJ9eVw6E",
"name": "John Myresaa"
},
"checkStatus": {
"status": 0,
"description": "New"
},
"checkStatements": [
{
"status": "created",
"date": "01/21/2026",
"time": "03:55 pm"
}
]
}
]
}
}
Action: Copy the checkId. You must have this to mail the check in the next step.
Step 4: Get Available Mailing Options
Before mailing a check, retrieve the available shipping methods and paper types. You'll need to select one of each for the mail request.
ENDPOINT (GET)
RESPONSE EXAMPLE
{
"success": true,
"data": {
"shippingTypes": [
{
"shippingTypeId": 1,
"name": "First Class",
"amount": "1.25"
},
{
"shippingTypeId": 3,
"name": "First Class with Tracking 7.50",
"amount": "7.50"
},
{
"shippingTypeId": 4,
"name": "Priority Mail USPS 12.99",
"amount": "12.99"
}
],
"paperTypes": [
{
"paperTypeId": 7,
"name": "Regular Check Paper",
"amount": "0.00"
},
{
"paperTypeId": 8,
"name": "Hollogram Check Paper",
"amount": "0.50"
},
{
"paperTypeId": 9,
"name": "Ultra Hollogram Check Paper",
"amount": "0.99"
}
]
}
}
Action: Choose one shippingTypeId and one paperTypeId for the next step.
Recommendation: For webhook tracking, choose a shipping type with tracking enabled (like shippingTypeId: 3 - "First Class with Tracking") to receive detailed delivery status updates.
Step 5: Mail the Check
This is the critical step! Submitting this request will trigger your check to be physically printed and mailed. It will also trigger your first webhook notification.
ENDPOINT (POST)
REQUEST BODY (JSON)
{
"mailChecks": [
{
"checkId": "1ZoVelMa5Mj8pwb",
"shippingTypeId": 3,
"paperTypeId": 7
}
]
}
REQUIRED FIELDS
- checkId - The check ID from Step 3
- shippingTypeId - Shipping method ID from Step 4
- paperTypeId - Paper type ID from Step 4
RESPONSE EXAMPLE
{
"success": true,
"message": "successfully mailed"
}
Important! Once this request completes successfully, your webhook endpoint will receive its first notification about the check status change.
Step 6: Receive Webhook Notification
After mailing the check, your configured webhook URL will automatically receive a POST request with the status update. Here's what the webhook payload looks like:
WEBHOOK PAYLOAD STRUCTURE
{
"event_id": "f298099f-25de-4a4f-a258-d48db8417ed7",
"event_name": "check.status.update",
"check_id": "1ZoVelMa5Mj8pwb",
"status": 4,
"mailing_status": []
}
WEBHOOK HEADERS (RECEIVED)
- signature - HMAC-SHA256 signature for validation (if you configured a secret key)
- timestamp - Unix timestamp when webhook was sent
- token - Your API token identifier
- content-type - application/json
PAYLOAD FIELD DESCRIPTIONS
- event_id - Unique identifier for this webhook event
- event_name - Type of event (always "check.status.update" for check status changes)
- check_id - The ID of the check that changed status
- status - Numeric status code (see status reference table below)
- mailing_status - Array of tracking updates (populates when tracking information becomes available)
About Webhook Signature Validation: If you configured a secret key in your webhook settings, OnlineCheckWriter signs each webhook request using HMAC-SHA256. The signature is sent in the request header and can be used to verify that the webhook genuinely came from OnlineCheckWriter and hasn't been tampered with. To validate: calculate the HMAC of the request body using your secret key and compare it to the signature header value.
Step 7: Verify Check Status via API
You can also manually query the check status at any time using the Check ID. This is useful for verification or if you miss a webhook notification.
ENDPOINT (GET)
URL PARAMETERS
- {checkId} - Replace with your actual check ID
RESPONSE EXAMPLE
{
"success": true,
"data": {
"checkId": "1ZoVelMa5Mj8pwb",
"serialNumber": "91001",
"amount": "100.00",
"amountInWord": " one hundred ",
"date": "2026-01-21",
"status": 4,
"memo": "First, Test check using API for Webhooks",
"bankAccount": {
"bankAccountId": "O7rWQ8Gpny7NjD0ZzpM",
"name": "AB COMPANY API Updated"
},
"payee": {
"payeeId": "bz3Aj3ZyJ9eVw6E",
"name": "John Myresaa"
},
"checkStatus": {
"status": 4,
"description": "Printing",
"shippingTypeId": 3,
"shippingTypeName": "First Class with Tracking 7.50",
"trackingNumber": null
},
"checkStatements": [
{
"status": "printing",
"date": "01/21/2026",
"time": "04:11 pm"
},
{
"status": "created",
"date": "01/21/2026",
"time": "03:55 pm"
}
]
}
}
Key Information: The checkStatus object provides detailed information including the human-readable description, shipping method, and tracking number (when available). The checkStatements array shows the complete history of status changes with timestamps.
Check Status Code Reference
Here are all possible status codes you may receive in webhooks or API responses:
| Status Code | Description | Meaning |
|---|
| 0 | Created | Check has been created but not yet processed |
| 1 | Printed | Check has been marked as printed (self-print or print-to-PDF) |
| 2 | Void | Check has been voided and cannot be used |
| 4 | Printing | Check is being processed for physical mailing (print facility) |
| 7 | Mailed | Check has been physically mailed via postal service |
| 11 | Refunded | Mailing fee has been refunded |
| 500 | Emailed | Check has been sent via email |
| 501 | Emailed and Viewed | Email check has been opened by recipient |
| 504 | Emailed and Tried to Print | Recipient attempted to print the emailed check |
| 505 | Emailed and Printed | Recipient successfully printed the emailed check |
| 807 | Mailed and Voided | Check was mailed but has been voided afterward |
Understanding Webhook Events
There are multiple webhook events available for different scenarios:
| Event Name | When It Fires |
|---|
| check.status.update | Fires whenever check status changes (created → printing → mailed, etc.) |
| check.mailing.tracking | Fires when USPS/FedEx tracking information is updated (in transit, out for delivery, delivered) |
| check.print.async | Fires for asynchronous print operations completion |
Note: The mailing_status field in the webhook payload will be empty initially. Once the check is physically handed to the shipping carrier and tracking begins, subsequent webhooks will include detailed tracking information in this field (such as "in transit", "out for delivery", "delivered", etc.).
Webhook Testing Best Practices
- Use a Webhook Testing Service: Tools like Webhook.site or RequestBin allow you to instantly create a webhook URL and view all incoming requests in real-time without writing any code.
- Test in Sandbox First: Always test your webhook integration in the sandbox environment before moving to production. This ensures you understand the webhook payload structure and timing.
- Implement Retry Logic: Your webhook endpoint should respond with HTTP 200 within 10 seconds. If it doesn't, OnlineCheckWriter may retry the webhook delivery.
- Validate Webhook Signatures: If you configured a secret key, always validate the webhook signature to ensure the request genuinely came from OnlineCheckWriter.
- Handle Duplicate Events: Use the
event_id to track which webhooks you've already processed, as webhooks may occasionally be delivered more than once. - Store Webhook Data: Log all webhook payloads to your database for auditing and debugging purposes.
- Monitor Webhook History: Use the "Webhook Logs" feature in the Developer Panel to view all webhook deliveries, their status, and any errors.
Troubleshooting Webhooks
Not Receiving Webhooks?
- Verify that "Enable Status" toggle is turned ON in your webhook settings
- Confirm that the specific event (e.g.,
check.status.update) is checked/selected - Ensure your webhook URL is publicly accessible (localhost URLs won't work)
- Check if your server/firewall is blocking incoming requests
- Verify your webhook endpoint returns HTTP 200 status code
- Review "Webhook Logs" in Developer Panel to see delivery attempts and errors
Webhook Signature Validation Failing?
- Ensure you're using the exact secret key configured in Developer Panel
- Verify you're hashing the raw request body (not parsed JSON)
- Use HMAC-SHA256 algorithm for signature calculation
- Compare signatures using a timing-safe comparison function
- Tracking information may take 24-48 hours to appear after mailing
- Only shipping methods with tracking will populate the
mailing_status field - In sandbox, some tracking features may be simulated or delayed
Need Help? If you encounter issues with webhooks, contact support via the Developer Panel or reach out on support@onlinecheckwriter.com
Complete Workflow Summary
- Setup: Configure webhook URL and API key in Developer Panel
- Get Bank Account ID:
GET /bankAccounts - Get Payee ID:
GET /payees - Create Check:
POST /checks with bankAccountId, payeeId, and amount - Get Mailing Options:
GET /mailchecks/mailingOptions - Mail Check:
POST /mailchecks with checkId, shippingTypeId, paperTypeId - Receive Webhook: Your webhook endpoint receives
check.status.update event - Verify Status:
GET /checks/{checkId} to confirm current status - Track Delivery: Receive additional webhooks as tracking information updates
Congratulations! You now have a complete webhook integration that automatically tracks your mailed checks from creation to delivery. Each status change will trigger a webhook notification to your configured endpoint, allowing you to build automated workflows and keep your customers informed in real-time.