Webhooks

Qué crosses el wire

• Dónde it sits

  Outbound, desde RapidCents a un routable HTTPS endpoint usted own. It runs en its own clock, independent de el request ese created el pago, y may arrive antes de o después de ese request returns.

• Qué usted receive

  UN JSON body describing one evento: its own identifier, its type, y el resource it concerns en el state it es now en. UN signature header accompanies it, computed over el exact bytes sent. El reference lists el evento types y el carga útil para each.

• Qué usted send back

  UN 2xx status y nothing else ese matters. Anything outside 2xx es read as un failure y schedules un redelivery, so un slow database write inside el handler turns into duplicate deliveries rather than un slow success.

Cuando a use it

• Keeping orders en sync

  Order status should follow el pago evento rather than un polling loop, que es both slower y heavier en el API than waiting a ser told.

• Reacting a disputes

  UN disputa evento gives usted el evidence window el day it opens rather than en month end, que es usually el difference entre responding y forfeiting.

• Closing el books

  El funded evento es el one finance cares Acerca de, because it names el lote un depósito came desde y lets un libro contable entry ser written against money ese actually arrived.

Cómo a implement Webhooks

Qué fails, y cómo usted find out

• Signature verified against a parsed body

  Framework software intermediario ese parses JSON y hands usted un object has already changed el bytes. El HMAC will no match, y el symptom es un valid evento rejected as forged.

• Events arriving out de order

  Retries mean un later evento puede land antes de un earlier one. Trust el state carried en el carga útil rather than el arrival order, y ignore un evento ese would move un resource backwards.

• UN handler ese acknowledges too late

  If su endpoint does el fulfilment work antes de returning, un timeout produces un redelivery y un second fulfilment. Acknowledge first, work second, y make el work safe a repeat.

• Un endpoint ese stopped listening

  Deliveries do no fail loudly en su side. Each attempt y its outcome es recorded against el evento, so un alert en repeated non-2xx responses es qué catches un silently broken consumer.

Sandbox versus production

• UN tunnel es un valid endpoint

  Entorno de pruebas (sandbox) deliveries reach any HTTPS tunnel a localhost, so signature verification puede ser built sin deploying anything. Production requires un routable address con un valid certificate.

• Events usted would otherwise wait days para

  Liquidación y funding events fire en un accelerated schedule en entorno de pruebas (sandbox), so el handler ese closes su books puede ser exercised en el same test run ese created el pago.

• Separate signing secrets

  El entorno de pruebas (sandbox) signing secret es no el production one. UN handler ese verifies correctly en entorno de pruebas (sandbox) will reject cada live evento if el secret fue no swapped en cutover, que es el single most common go-live failure.