Webhooks and events

Plan event-driven processing for Roots review, account, payment, and RFI state changes.

See API availability for current event-delivery availability.

Planned event categories

Your integration should be ready to process events in these categories when Roots publishes the event contract:

• Review outcomes and escalations.
• Account issuance, activation, restriction, hold, and closure.
• Counterparty screening outcomes.
• Payment state changes.
• RFI creation, response review, and resolution.
• First-funding review outcomes and funds-availability changes.

flowchart LR
  Roots[Roots] -->|Event delivery| Receiver[Your webhook receiver]
  Receiver -->|Persist event| Queue[Internal queue]
  Queue -->|Process idempotently| Workflow[Onboarding, payment, or case workflow]
  Workflow -->|Retrieve current state| Roots

Design your receiver now

1. Receive events on a dedicated HTTPS endpoint.
2. Persist the raw event and your received timestamp before business processing.
3. Process events asynchronously.
4. Make handlers idempotent so duplicate delivery does not create duplicate actions.
5. Retrieve the current Roots resource before you change funds access or report settlement.
6. Keep RFI, hold, and restriction handling fail closed.

Target schema — confirm in API reference

Roots has not yet published a webhook contract. Do not implement a receiver against assumed details.

Confirm the following before enabling event delivery:

• Event names and payload schemas.
• Registration and endpoint-verification flow.
• Signature header and verification algorithm.
• Retry schedule, timeout behavior, and delivery-success response codes.
• Ordering, duplicate delivery, and replay behavior.
• Event retention and redelivery controls.

Next steps

• Read Track payment status for state-based payment handling.
• Read Holds, restrictions, and RFIs for fail-closed workflows.
• Read Security and data handling before accepting external requests.