Webhooks

What crosses the wire

• Where it sits

  Outbound, from RapidCents to a routable HTTPS endpoint you own. It runs on its own clock, independent of the request that created the payment, and may arrive before or after that request returns.

• What you receive

  A JSON body describing one event: its own identifier, its type, and the resource it concerns in the state it is now in. A signature header accompanies it, computed over the exact bytes sent. The reference lists the event types and the payload for each.

• What you send back

  A 2xx status and nothing else that matters. Anything outside 2xx is read as a failure and schedules a redelivery, so a slow database write inside the handler turns into duplicate deliveries rather than a slow success.

When to use it

• Keeping orders in sync

  Order status should follow the payment event rather than a polling loop, which is both slower and heavier on the API than waiting to be told.

• Reacting to disputes

  A dispute event gives you the evidence window the day it opens rather than at month end, which is usually the difference between responding and forfeiting.

• Closing the books

  The funded event is the one finance cares about, because it names the batch a deposit came from and lets a ledger entry be written against money that actually arrived.

How to implement Webhooks

What fails, and how you find out

• Signature verified against a parsed body

  Framework middleware that parses JSON and hands you an object has already changed the bytes. The HMAC will not match, and the symptom is a valid event rejected as forged.

• Events arriving out of order

  Retries mean a later event can land before an earlier one. Trust the state carried in the payload rather than the arrival order, and ignore an event that would move a resource backwards.

• A handler that acknowledges too late

  If your endpoint does the fulfilment work before returning, a timeout produces a redelivery and a second fulfilment. Acknowledge first, work second, and make the work safe to repeat.

• An endpoint that stopped listening

  Deliveries do not fail loudly on your side. Each attempt and its outcome is recorded against the event, so an alert on repeated non-2xx responses is what catches a silently broken consumer.

Sandbox versus production

• A tunnel is a valid endpoint

  Sandbox deliveries reach any HTTPS tunnel to localhost, so signature verification can be built without deploying anything. Production requires a routable address with a valid certificate.

• Events you would otherwise wait days for

  Settlement and funding events fire on an accelerated schedule in sandbox, so the handler that closes your books can be exercised in the same test run that created the payment.

• Separate signing secrets

  The sandbox signing secret is not the production one. A handler that verifies correctly in sandbox will reject every live event if the secret was not swapped at cutover, which is the single most common go-live failure.