Payment webhook
FreeFlow@rabbinatix/payment-webhook by Rabbinatixupdated Oct 13, 2026
The payment provider tells you a payment succeeded or failed; each event is checked, handled once, and the order follows.
What happens after the card form, when the payment provider calls you back:
- Payment provider sends the event with a signature, and retries it when you don’t answer 200.
- Order service checks the signature, remembers every event so one sent twice changes nothing, finds the order and marks it paid, or failed and emails the customer.
- Shop database keeps the orders and the events seen. Mailer sends the "payment failed" email.
Tricky steps: providers send the same event more than once, and not always in order, so the event id is remembered before anything changes. An event you don’t handle, or for an order you don’t know, still gets 200: otherwise the provider retries it for days.
Previewlanes are roles; you pick your systems when importing
- No matches
Not foundNot foundFalse400Other
Start in Payment provider. step 1 of 25. key stepOn Payment changed
Call to another system in Payment provider. step 2 of 25. key stepSend the webhook
Start in Order service. step 3 of 25. key stepOn POST /api/v1/webhooks/payments
Step in Order service. step 4 of 25. key stepSignature right?
Resource in Order service. step 5 of 25Handled this event before?
Answer in Shop database. step 6 of 25. key stepwebhook_events.findById
Return in Order service. step 7 of 25. key stepSent again → 200, nothing changes
Resource in Order service. step 8 of 25Remember the event
Answer in Shop database. step 9 of 25. key stepwebhook_events.insert
Resource in Order service. step 10 of 25. key stepFind the order
Answer in Shop database. step 11 of 25. key steporders.findById
Resource in Order service. step 12 of 25. key stepMark the order paid
Answer in Shop database. step 13 of 25. key steporders.setStatus
Return in Order service. step 14 of 25. key stepPaid → 200
Resource in Order service. step 15 of 25Mark the payment failed
Answer in Shop database. step 16 of 25. key steporders.setStatus
Resource in Order service. step 17 of 25Ask the customer to pay again
Answer in Mailer. step 18 of 25. key stepmail.sendPaymentFailed
Return in Order service. step 19 of 25. key stepFailed → 200
Return in Order service. step 20 of 25. key stepOther event → 200, ignored
Return in Order service. step 21 of 25. key stepNot our order → 200, no retry
Return in Order service. step 22 of 25. key stepNot from the provider → 400
Return in Payment provider. step 23 of 25. key stepReturn
Return in Payment provider. step 24 of 25. key stepReturn
Return in Payment provider. step 25 of 25. key stepReturn
Payment provider
External API
Order service
Backend service
Shop database
Database
Mailer
External API
Up and down arrows: previous or next step. Home, End: first or last. Enter: select. Shift F10: more actions.
APIs
POST{base}/webhooks/payments· The payment provider tells us a payment changed
Order service provides it · Payment provider calls it
Request body
eventId: string type: string orderId: string amount: number
200
result: string
400
error: string
Data operations
webhook_events.findByIdqueryon Shop database(eventId: string)
webhook_events.insertinserton Shop database(eventId: string, type: string)
orders.findByIdqueryon Shop database(orderId: string)
orders.setStatusupdateon Shop database(orderId: string, status: string)
mail.sendPaymentFailedcallon Mailer(to: string, orderId: string, amount: number)
Test cases
Payment succeeded: order paid→ Delivered: order paid
Payment failed: customer asked to pay again→ Delivered: payment failed
Same event sent twice→ Delivered again: nothing changed
Bad signature→ Refused: bad signature
An event we don’t handle→ Delivered: ignored
An order we don’t know→ Delivered: not our order
Requirements
Only events signed with our shared secret change an order.
Each event changes an order at most once, however often it is sent.
Events we don’t handle, or for orders we don’t know, are acknowledged so the provider stops retrying.
A failed payment marks the order and asks the customer to pay again.
Roles (4)
Payment provider
Sends the webhook, like Stripe, Adyen or Paddle · External API
Order service
Receives the webhook and updates the order · Backend service
Shop database
Orders, and the events already handled · Database
Mailer
Sends the "payment failed" email · External API or backend service
Settings
Order id fieldorderId (renamable)
Also as a whiteboard
Versions
