If you run a CRM, an ERP or an automation tool next to your Instagram shop, you do not want to copy orders across by hand. Webhooks push order and return events from Checkout DM to your own system the moment they happen, with full order, customer and item detail. There is no polling. Webhooks are a Pro plan feature.
Setting one up
- Open Webhooks in your dashboard and add your endpoint URL. It must be an HTTPS address.
- Pick the events you want. You can choose any of the available events for each webhook.
- Save the secret. When the webhook is created, its secret is shown once. Copy it straight away, because you need it to verify incoming requests. Afterwards only the last four characters are shown.
You can have up to 10 webhooks per account. Each can be switched off and back on, or removed, from the list. Removing one stops all events to that URL immediately.
The six events
| Event | When it fires |
|---|---|
| order.created | A new order is placed, before payment. There is no order number or status yet, because those are assigned once it is paid. |
| order.paid | Payment is confirmed, through Razorpay, Stripe, PayPal or manual UPI. |
| order.shipped | You mark the order as shipped from the dashboard. Includes the shipped time. |
| return.requested | A customer asks for a return, from the dashboard or Instagram DM. |
| return.approved | You approve a return request. Includes your note if you added one. |
| return.rejected | You reject a return request. Includes your note if you added one. |
What a payload contains
Four fields are always present: the event name, your business ID, an entity ID and a timestamp. Everything else, such as order, customer, address and item detail, is included where it is relevant and available, so the exact fields vary by event. A few specifics are worth knowing before you write your integration:
- Amounts are strings, not numbers. The total and the shipping fee are sent as strings to avoid rounding problems on money values. Item price is a plain number. Parse amounts explicitly.
- Order number and status are absent on order.created, because they are assigned right after payment. Status appears on order.paid only.
- Customer email may be missing on a return requested over Instagram DM, because email is not always captured in that flow. It is always present on order events.
- Discount is always present as a key, but its value is null when no coupon was applied.
- Reason appears only on the three return events, and merchant note only on return.approved and return.rejected.
- Return items reflect only the items being returned when that data is available, falling back to the full order’s items otherwise.
The practical advice is to write defensively: check that a field exists before reading it instead of assuming every field appears on every event.
What an order.paid payload looks like
To make this concrete, an order.paid event carries the four always-present fields plus the order details: an order number in the CDM-000044 style, the customer’s name, phone and email, the delivery address, the total amount and currency, the status paid, the shipping fee, the discount (null if none) and a list of items with their names and prices. A return.approved event looks similar, with the reason the customer gave and your merchant note added, and it lists the items being returned. The webhooks guide shows both as real sample payloads, so you can build and test your receiving code against them.
Verifying signatures
Every request carries an X-CheckoutDM-Signature header. It is an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. Always verify it before trusting a payload, and compute it from the raw bytes exactly as received. Even one extra space produces a different hash, so do not re-serialize the JSON first. The Checkout DM webhooks guide includes a worked example.
Retries and failed deliveries
If your endpoint does not answer with a 2xx status, Checkout DM retries automatically for a few attempts. After that, the delivery stops retrying on its own, but it is not lost. Open Webhooks in your dashboard and it is listed under Failed deliveries, grouped by the webhook it belongs to, with a one-click Resend once your endpoint is back up. Return a 2xx quickly, ideally within a few seconds, once you have accepted the event, and do any slow processing afterwards on your side.
Related reading
Frequently asked questions
Which plan includes webhooks?
Webhooks are a Pro plan feature.
How many webhooks can I create?
Up to 10 per account. Each one must use an HTTPS endpoint URL.
Which events are available?
order.created, order.paid, order.shipped, return.requested, return.approved and return.rejected.
How do I verify a webhook really came from Checkout DM?
Compute an HMAC-SHA256 of the raw request body using your webhook secret and compare it with the X-CheckoutDM-Signature header.
Can I pause a webhook without deleting it?
Yes. Each webhook in your list can be switched off and back on, or removed entirely, which stops all events to that URL immediately.
Are amounts sent as numbers?
No. The total and the shipping fee are sent as strings to avoid rounding problems, while the item price is a plain number. Parse amounts explicitly.
What happens if my endpoint is down?
Checkout DM retries a few times, then stops. The delivery appears under Failed deliveries in your dashboard, where you can resend it once your endpoint is back.


