You can configure your account to receive notifications via a webhook by following the steps below:

• Log into your Checkissuing account.
• Click on the settings link in the left sidebar.
• Click on the 'Options' tab, enter the url you want notifications sent to in the 'Webhook URL' input and save.

Webhook Sending / Procedures

Checkissuing does not check the reply to webhooks, we only check for general deliverability. If we receive an http status code of 200 or another indicator that it was received properly, we mark it as successful on our end and do not try to resend. If we get an error indicating that it was not received ok, we will attempt to resend the webhook in question.

We try to resend a webhook up to 10 times. How often depends on our queuing system, what we have queued, the current stuff that’s queued’s priority (in relation to it), & a variety of other factors however there is a minimum of a 5 minute delay between attmpts. On average a webhook will retry every 5-10m (usually closer to 5) but there’s no exact way to tell at any given time the exact interval.

After 10 attempts, we mark it as undeliverable and it will be stored in our queue as such for up to 2 days, so if for whatever reason we need to, we can go back up to 2 days and force it to retry those if we are notified/it is requested.

Verifying Webhook Authenticity

Checkissuing can include HMAC-SHA256 signatures when sending webhooks that allow you to validate their authenticity. In order to enable this, login to your account and go to Settings > Options. You will see an input labelled 'Webhook Signature Secret'. Enter a secure/secret string here and click the 'Save Changes' button. This sets your Webhook Secret to the string you provided, once this is set, all webhooks sent will include two additional HTTP headers, CI-Signature-Timestamp and CI-Signature.

In order to validate received webhooks, generate a HMAC-SHA256 hash by concatenating the value of CI-Signature-Timestamp, a '.', and the webhooks json data (as a string), using your Webhook secret as the key. If this hash matches the value of the CI-Signature header, the webhook is authentic/valid.

Available Webhooks

Below is a list of webhooks that get sent with an example for each. They are grouped by the type of entity (general account events, payment events, document events) so consumers can quickly find the events they care about.

General / Account Webhooks

security_alert

Sent when there is a security alert

{"event_type":"security_alert","alert_text":"Description of the alert in question"}

user_added

Sent when a user is added

{"event_type":"user_added","user_id":323,"username":"AUser"}

Payment Webhooks

payment_added

Sent when a payment is added

{"event_type":"payment_added","payment_id":323,"payee":"Some Payee","amount":"5.00"}

payment_updated

Sent when a payment is updated

{"event_type":"payment_updated","payment_id":323}

payment_flagged

Sent when a payment is flagged

{"event_type":"payment_flagged","payment_id":323}

payment_status_change

Sent when a payment's status changes

{"event_type":"payment_status_change","payment_id":323,"new_status_id":4}

payment_needs_repaired

Sent when a payment needs repaired

{"event_type":"payment_needs_repaired","payment_id":323,"errors":"Errors with the payment"}

tracking_added

Sent when a tracking number is recorded or changed for a payment. Fired regardless of how the tracking value was supplied, and the payload shape is the same in every case.

{"event_type":"tracking_added","payment_id":323,"tracking_id":1011,"tracking_number":"9400111899223456789012","tracking_carrier":"USPS","tracking_status":"pending","tracking_status_updated_at":"2025-04-20T12:00:00Z"}

payment_tracking_status

Sent when an existing payment tracking number's carrier-reported status changes (for example, in_transit → delivered). The tracking_info value contains the full carrier response; see Sample Payment Tracking Response for the response shape.

{"event_type":"payment_tracking_status","payment_id":323,"tracking_id":1011,"tracking_number":"9400111899223456789012","tracking_carrier":"USPS","tracking_status":"delivered","tracking_status_updated_at":"2025-04-22T14:05:11Z","previous_status":"in_transit","new_status":"delivered","tracking_info":{"message":null,"data":{"expected_delivery_date":"2025-04-22","scans":[{"scan_date_time":"2025-04-22T10:14:32","scan_facility_city":"LOS ANGELES","scan_facility_state":"CA"}]}}}

Document Webhooks

Documents emit webhooks for upload, status changes, and the lifecycle of any tracking number attached to a document. Tracking events fire when a tracking number is first recorded for a document, when an existing tracking record is edited, and when the carrier-reported status of that tracking number changes.

docs_uploaded

Sent when one or more documents are uploaded to your account.

{"event_type":"docs_uploaded","document_ids":[789,790,791]}

document_status_change

Sent when a document's status changes (for example, queued → printed → mailed).

{"event_type":"document_status_change","document_id":789,"new_status_id":4}

document_tracking_added

Sent the first time a tracking number is recorded for a document.

{"event_type":"document_tracking_added","document_id":789,"file_id":null,"tracking_id":2042,"tracking_number":"9400111899223456789012","tracking_carrier":"USPS","tracking_status":"pending","tracking_status_updated_at":"2025-04-20T12:00:00Z"}

document_tracking_updated

Sent when a document's tracking row is updated — for example, when the tracking number, carrier, or carrier service is changed (but the carrier-reported status itself has not changed).

{"event_type":"document_tracking_updated","document_id":789,"file_id":null,"tracking_id":2042,"tracking_number":"9400111899223456789012","tracking_carrier":"USPS","tracking_status":"in_transit","tracking_status_updated_at":"2025-04-21T08:30:00Z"}

document_tracking_status_changed

Sent when a document's tracking status changes (for example, in_transit → delivered).

{"event_type":"document_tracking_status_changed","document_id":789,"file_id":null,"tracking_id":2042,"tracking_number":"9400111899223456789012","tracking_carrier":"USPS","tracking_status":"delivered","tracking_status_updated_at":"2025-04-22T14:05:11Z","previous_status":"in_transit","new_status":"delivered"}