Skip to main content

Webhook Delivery Problems

Webhooks are managed on Settings → Webhooks: click your name in the top right of the dashboard, then Webhooks under Developer. It is a main-account page, and webhooks need a paid plan. Lead Board Stage Change webhooks need the Business plan or higher.

Symptom: Webhook not receiving events​

  1. Confirm the webhook has the right Type: Order Item (Recipient) Status Update, Order Status Update, Order Item (Recipient) Delivered, QR Code Scan Notification, or Lead Board Stage Change. Each webhook has one type; add one webhook per type you need.
  2. Confirm the endpoint URL is publicly accessible - webhooks cannot reach localhost or internal network addresses.
  3. Use Send Test in the webhook's menu to send a test event to your endpoint. The dashboard confirms the test as sent even if your endpoint rejects it, so check your endpoint's logs to see that it arrived.
  4. Check the webhook's Mailing List and Subaccount fields. A webhook with a mailing list chosen only fires for orders sent to that list, and one with a subaccount chosen only fires for that subaccount's orders. Set either to None to widen it.

Symptom: Receiving duplicate events​

thanks.io delivers at-least-once. Return a 2xx response as quickly as possible, and make your consumer idempotent - store the event ID and skip processing if you've already handled it.

Symptom: Payload missing expected fields​

  1. Review the full payload structure for each event type at docs.thanks.io.
  2. Log the raw incoming payload and compare to the documented schema.
  3. Use Send Test in the webhook's menu to capture a sample payload.

Symptom: Endpoint returning 4xx/5xx and events not retrying​

  1. Fix the underlying error in your endpoint. Check your server logs.
  2. 400 Bad Request usually means a parser mismatch - verify your endpoint parses application/json.
  3. 401/403 means your endpoint is enforcing auth - remove it for the webhook path.
  4. Once your endpoint is healthy, send a test event to confirm delivery is restored.

Symptom: Wrong account events being received​

All webhooks belong to the main account. A webhook with Subaccount set to None receives events from the main account and every subaccount; each payload's order.sub_account_id says which one it came from. To send one subaccount's events to its own endpoint, edit the webhook (or add another) and choose that subaccount in Subaccount.

Symptom: Lead Board stage webhook not firing​

  1. Confirm the webhook's Stage is the column you moved the card into. On the Webhooks page, the stage shows under the type; on the Lead Board, each column's webhook button shows how many webhooks it has.
  2. Each stage webhook fires once per card. If the card has entered that column before, moving it out and back in doesn't send it again. Try a card that has never been in that column.
  3. Cards loaded onto the board from past scans didn't fire New webhooks. A New webhook fires on the first scan of a piece from then on.
  4. Check that the card is for scanned mail. Cards for callers to your AI Receptionist number (marked with a phone icon) never fire stage webhooks.
  5. Check your plan. Stage webhooks only fire on the Business plan and up; an account on the Free plan keeps them, but they don't fire until it upgrades.
  6. Check the webhook's Mailing List and Subaccount fields. With either chosen, it only fires for cards from mail sent to that list or from that subaccount.
  7. If the URL uses replacement variables like ~FIRST_NAME~, use Send Test and check your endpoint's logs for the URL it received. A variable the recipient has no value for is left empty.

Symptom: Birthday or thank-you campaign webhook not firing​

  1. Confirm the campaign is actively sending. Open Campaigns, click the campaign, and check that the action reads Running.
  2. Confirm the correct webhook type is set up: Order Item (Recipient) Status Update (fires as each piece's status changes) or Order Item (Recipient) Delivered (fires on delivery). Birthday/holiday campaigns create orders just like any other campaign, so the same webhook events fire.
  3. If the campaign belongs to a subaccount, confirm the webhook's Subaccount is None or that subaccount, and that its Mailing List (if set) is the campaign's list.
  4. Check your webhook endpoint with Send Test to confirm it receives events.
  5. If the campaign has never fired at all, check Campaign Not Triggering first.