Webhook events

Webhook events is a page in the control plane that lists the messages Stripe, Resend and Twilio send to HoW, and how each one ended. It shows the ones HoW gave up on, the failed and the ignored ones first, because those are the ones someone may have to look at. A Stripe event that failed is tried again on its own; one HoW gave up on can be retried from here.

This is not the church-facing “API keys and webhooks” feature: that one is about the webhooks a church sends to its own systems. This page is about the webhooks providers send to HoW.

How to use it

1. Sign in to the control plane and open Webhook events in the menu. The page opens on Gave up, failed and ignored, newest first, 50 events a page.
2. To narrow the list, use the status filter: Gave up, failed and ignored, Gave up, Failed, retrying, Ignored, Processed, Received, not yet handled or Any status. Changing a filter takes you back to the first page.
3. To see one provider only, choose it in Any provider (for example Stripe). Clear it to see them all again.
4. If a church or a teammate gives you the provider’s own event id (a Stripe one starts with evt_), type it in Find an event id. The page shows that one event whatever its status, and the two filters are switched off until you clear the box.
5. Choose a row to open it. The panel shows its Status, Church, Provider, Provider’s event id, Received, Handled, Attempts, Next attempt (for one that is retrying) and Reason. The church’s name links to that church’s page in the control plane. A Stripe event that failed or that HoW gave up on has a Retry button (below).
6. Use the page numbers at the bottom to go back further in time.

The Overview also shows Webhooks failed, last 24 hours. It turns red when the count is above zero, and Open takes you straight to the failed events. It counts events that failed or that HoW gave up on, not ignored ones.

Reading an event

The columns

• Received: when the provider’s message reached HoW, in your computer’s time zone.
• Provider: who sent it: Stripe, Resend or Twilio.
• Event: the provider’s own name for what happened, such as checkout.session.completed (someone finished paying) or account.updated (a church’s Stripe account changed).
• Status: how it ended (below).
• Church: the church the event belongs to. No church means HoW could not match it to any church.
• Reason: why it was ignored or failed, in HoW’s words. A dash means no reason was recorded.

The statuses

• Processed: HoW did what the event asked, such as marking a registration paid. Nothing to do.
• Ignored: HoW recorded the event and chose, on purpose, not to act on it. Most are harmless; a few are warnings (below).
• Failed, retrying: HoW tried to act and could not, and will try again on its own: after 1 minute, then 4, 16, 64, and so on, never more than a day apart. Stripe also sends it again. Usually nothing to do; it clears itself.
• Gave up: HoW tried ten times (about four days) and could not, or set the event aside on purpose (a payment for less than was due). Always worth a look.
• Received, not yet handled: HoW recorded the event but has not finished with it (the panel says Handled: Not yet). HoW picks it up again by itself after two minutes; one that stays like this longer is worth a look.

Retries. HoW keeps each provider event once, and tells Stripe it arrived only once it has been handled. When handling fails, HoW tells Stripe so, and both Stripe and HoW try again. When Stripe sends an event HoW already handled, HoW does nothing more. When it sends one HoW has not finished with (failed, gave up, or still received), including when someone resends it from Stripe’s dashboard, HoW handles it again. Each time, HoW asks Stripe for the payment, refund or account as it is now, so an old or repeated event can never undo something newer.

What “Ignored” means for Stripe. The reason tells you which case it is:

• A dash, no reason. A kind of Stripe event HoW does not use. Stripe sends many; HoW acts only on payments, refunds and changes to a church’s Stripe account. Nothing to do.
• “no church holds this connected account”. The Stripe account the event is about is not connected to any church in HoW. Nothing to do, unless a church tells you its payments stopped arriving.
• “no registration or order in the session’s metadata”. A payment the church took in Stripe directly, not through HoW. Nothing to do.
• “nothing of ours holds this payment”. A refund, made in the church’s own Stripe account, of a payment HoW never handled. Nothing to do.
• “no registration or payment intent on the refund”. A refund HoW cannot tie to any payment. Usually nothing to do; look closer if the church says a refund is missing in HoW.
• “the registration in the metadata is not this church’s” (or “the order in the metadata …”). A payment or refund on one church’s Stripe account named another church’s registration or order, and HoW refused to touch it. This is a security warning; see the next section.

Resend and Twilio. Their events do not appear on this page yet. Email delivery updates and text replies still work; they are just not listed here. When they are added, this article will say what “Ignored” means for each.

What to do about a failed event

1. Open the event and read the reason. Note the church and the provider’s event id. An event that says Failed, retrying is being retried on its own; you only need to act if it ends in Gave up.
2. “paid … for … due; not recorded as paid”. Someone completed a payment for less than HoW asked for. The amounts are in cents: “paid 4500 for 5000 due” is $45.00 paid for $50.00. HoW left the registration or order unpaid, on purpose. This can mean someone tampered with the checkout, so treat it as a security matter: escalate it to the DCX Logic owner with the event id, and follow the incident-response runbook. Do not mark anything paid yourself.
3. Any other reason, on an event HoW gave up on. Something went wrong on HoW’s side, such as a payment, a refund or a church’s Stripe account status that was not recorded. Look the event up in Stripe’s dashboard by its id (Stripe shows it under the church’s connected account) to see what Stripe says happened, then check the church’s record in HoW. Send the event id, the church and the reason to engineering. Once they say the cause is fixed, choose Retry in the event’s panel: HoW tries it again within a minute, from what Stripe says now, and the status changes to Processed. Do not retry an underpayment (step 2). Nobody fixes an event by changing the live database by hand.
4. Tell the church when its people are affected: someone paid but their registration or order still shows unpaid, a refund does not show, or the church’s payments setup looks stuck. Say what you see and that it is being fixed; you do not need to explain webhooks. When nothing the church sees is wrong, there is nothing to tell them.
5. For an ignored security warning (a record that is not the church’s), escalate it the same way as an underpayment. Never name one church to another.

Good to know

• Who can open it. Platform super admins only. DCX support staff do not see it in the menu, and going to the page shows You do not have access; the overview count is hidden from them too. Church staff, owners included, never reach the control plane at all. HoW checks this on the server, not just on the screen.
• Retry is the one thing it changes. It puts a failed or gave-up Stripe event back in the queue; it never edits a church’s records itself, and HoW records who retried what. Events from other providers cannot be retried here.
• It never shows what the provider sent. A Stripe message can carry a payer’s name, email or address, and a text or email update can carry a member’s details. The page shows only when, who, what kind, how it ended and why. To see the full message, look the event up by its id in the provider’s own dashboard.
• Ignored is not the same as broken. Most ignored events are Stripe telling HoW about things HoW does not need. Read the reason before raising an alarm.
• Empty is good news. Nothing gave up, failed or was ignored with “Every webhook that arrived was handled.” means just that.

If something isn’t right

• “Could not load webhook events.” Choose Try again. If it keeps happening, tell engineering.
• “Not available” on the Overview count means HoW could not read it, not that nothing failed. Open the page instead.
• “No event with the id …” Check the id against the provider’s dashboard: copy it exactly, including the evt_ prefix. Resend and Twilio ids will not be found yet, because those events are not listed here.
• You see “You do not have access” and you are a super admin: sign out and back in. If it persists, ask the DCX Logic owner to check your platform role.
• A church says a payment or refund did not go through and nothing shows here: search for the event id from the church’s Stripe account, then switch the status filter to Any status to check it was processed.