Using Webhooks

Overview

Webhooks enable one service to automatically send real-time updates to another, eliminating the need for manual checks. Think of them as instant notifications - whenever a specific event occurs in the sending system, the receiving system is alerted immediately.

In the context of thanks.io, webhooks provide an efficient way to receive proactive alerts about various events, including USPS tracking updates and QR Code Scans. Common webhook use cases include:

Receiving notification when a recipient scans the QR Code on a mailer
Getting notified when mailpieces fails to send
Triggering workflows upon final delivery confirmation

Setup

Please contact us at support@thanks.io with your URL and what events you would like to monitor.

Webhook Types

Below are the various event types that can be monitored

QR Code Scans

This event will fire whenever a recipient scans a thanks.io QR Code on your mailer.

Example:

{
    "event_type": "order_item.status_update",
    "event_id": "c4e1aa40-516a-11f0-94e9-4b4494619f64",
    "data": {
        "order_item.id": 2668661,
        "order_item.scans": 4,
        "order_item.failure": null,
        "recipient.name": "John Doe",
        "recipient.company": null,
        "recipient.address": "123 Fake St",
        "recipient.address2": null,
        "recipient.city": "Any Town",
        "recipient.province": "NY",
        "recipient.postal_code": "12345",
        "recipient.country": "US",
        "recipient.email": null,
        "recipient.phone": null,
        "recipient.custom_1": "Example Custom 1",
        "recipient.custom_2": "Example Custom 2",
        "recipient.custom_3": "Example Custom 3",
        "recipient.custom_4": "Example Custom 4",
        "order.id": 42398,
        "order.status": "Fulfilled",
        "order_item.delivery_date": "2025-06-05",
        "order_item.current_status": "Processing",
        "qrcode.url": "https://www.google.com"
    },
    "timestamp": 1750817946,
    "date_time": "2025-06-25 02:19:06"
}

Order Status Change

This event will fire whenever an Order changes status. Info on Order Status types can be found here.

Possible Status Types are:

Reviewing - Order is within hour cancellation window.
Printing - Mail pieces are being sent to printer network.
Printed - All mail pieces have been sent to printer network.
Fulfilled - All processing related to order is completed (notifications, order settled.)
Shipped - Mail pieces have been shipped.
Delivered - A mail piece has been delivered for this order.
Cancelled - Order was cancelled by client.
Error - All items in order were not able to be printed.

Example:

{
    "event_type": "order.status_update",
    "event_id": "a8a59df0-516d-11f0-9ca2-31daad0e4f7f",
    "data": {
        "order.id": 42401,
        "order.status": "Printing",
    },
    "timestamp": 1750819187,
    "date_time": "2025-06-25 02:39:47"
}

Order Item Status Change

This event will fire whenever an Order Item changes status. Info on Order Item Status types can be found here.

Possible Status Types are:

Delivered
Processing
In Transit
In Local Area
Processed for Delivery
Re-routed
Returned to Sender
Printed
Shipped
Failed

Example:

{
    "event_type": "order_item.status_update",
    "event_id": "7199e4e0-516b-11f0-ba5f-f135ea42fb62",
    "data": {
        "order_item.id": 2668662,
        "order_item.scans": null,
        "order_item.failure": null,
        "recipient.name": "John Doe",
        "recipient.company": null,
        "recipient.address": "123 Fake St",
        "recipient.address2": null,
        "recipient.city": "Any Town",
        "recipient.province": "NY",
        "recipient.postal_code": "12345",
        "recipient.country": "US",
        "recipient.email": null,
        "recipient.phone": null,
        "recipient.custom_1": "Example Custom 1",
        "recipient.custom_2": "Example Custom 2",
        "recipient.custom_3": "Example Custom 3",
        "recipient.custom_4": "Example Custom 4",
        "order.id": 42399,
        "order.status": "Printing",
        "order_item.delivery_date": "2025-07-05",
        "order_item.previous_status": null,
        "order_item.current_status": "Processing"
    },
    "timestamp": 1750818235,
    "date_time": "2025-06-25 02:23:55"
}