Webhook events

RCM emits authenticated webhooks for asynchronous events. The most important ones today carry the outcome of running a support file through DVS (Document Validation Service) — classification, then validation against the payer's rule set.

Each subscription is authenticated with either an HMAC-SHA256 signature (default) or HTTP Basic credentials — see Authentication.

This page is the contract: how to receive, verify, and parse RCM webhooks. The event-by-event payloads live in Classification events and Validation events.

Delivery model

RCM expects a 2xx response. Any other status code (3xx/4xx/5xx) or a connection/read timeout is treated as a failure. Failed events are re-attempted by the dispatcher on its next scheduling cycle (roughly once per minute) while the event is still pending. After several consecutive failures, the subscription's circuit breaker opens and delivery is suspended until it resets automatically (or is reset manually).

Your receiver MUST be idempotent — the same event may be delivered more than once (at-least-once semantics). Use the event_id field (mirrored in the X-RCM-Event-ID header) as your dedupe key. There is no ordering guarantee across events.

Common headers

Every RCM webhook ships with these headers:

Header	Example	Description
Content-Type	application/json	Body is JSON, UTF-8.
X-RCM-Event-Type	DOCUMENT_VALIDATION_COMPLETED	One of the documented event types. Use this to route.
X-RCM-Event-ID	3fa85f64-5717-4562-b3fc-2c963f66afa6	UUID. Stable across retries of the same event. Use for idempotency.
X-RCM-Timestamp	2026-06-25T15:34:00.123-06:00	ISO-8601 timestamp at which the delivery (and signature) was computed. Reject if the skew is > 5 minutes.
X-RCM-Signature	k3m9...==	HMAC subscriptions only. Base64 HMAC-SHA256 of timestamp + raw_body. See signature verification.
Authorization	Basic cmVkLi4u	Basic subscriptions only. Basic base64(client_id:client_secret). See Authentication.

RCM also forwards any custom headers you configured on the subscription (e.g. an API key of your own). The authentication header is always applied last, so it stays authoritative over custom headers.

Body envelope

Every event uses the same outer shape — only payload varies by event type:

{
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event_type": "DOCUMENT_VALIDATION_COMPLETED",
  "entity_type": "support_file",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payload": {
    "...": "event-specific fields — see Classification / Validation pages"
  },
  "metadata": {},
  "created_at": "2026-06-25T15:34:01.000-06:00"
}

Field	Type	Description
event_id	string (UUID)	Same value as the X-RCM-Event-ID header. Use for idempotency.
event_type	string	Same value as X-RCM-Event-Type. Always one of the documented types.
entity_type	string	Domain entity this event is about: support_file for validation events, support_document for classification events, charge_audit_item for RGA audit events.
entity_id	string (UUID)	ID of the related domain entity.
payload	object	Event-specific payload. The shape is documented per event.
metadata	object	Additional system metadata; may be empty ({}).
created_at	string (ISO-8601)	When the event was created.

JSON is snake_case

The envelope, the subscription request you send us, and the validation and audit payloads use snake_case field names, and omit fields with a null value — do not assume optional fields are present. One exception: the payload of classification events uses camelCase keys and keeps null fields.

Event catalog

Events RCM emits today:

Event	When it fires
DOCUMENT_CLASSIFICATION_COMPLETED	A support file uploaded via the v2 endpoint was classified and associated by DVS.
DOCUMENT_CLASSIFICATION_FAILED	DVS could not classify/associate a support file.
DOCUMENT_VALIDATION_COMPLETED	DVS evaluated the support file against the payer's rules and it APPROVED.
DOCUMENT_VALIDATION_REJECTED	DVS evaluated the support file and it REJECTED (one or more rules failed).

Validation events are emitted regardless of whether the upload was v1 (with support_file_code provided) or v2 (auto-classify). Classification events are only emitted for v2 auto-classify uploads.

RCM also produces a separate family of events for payer audits in Brazil — CHARGE_AUDIT_ACCEPTED, CHARGE_AUDIT_UPDATED, CHARGE_AUDIT_DELETED and CHARGE_AUDIT_PENDING, one per audited item of an Orizon RGA report. Those are consumed over the pull API rather than push webhooks; see Audit events.

These eight are the events with a stable, fully specified payload. RCM also emits account, charge, invoice and settlement-batch events (ACCOUNT_*, CHARGE_*, INVOICE_*, SETTLEMENT_GROUP_*) whose payload is still in preview. The complete list, including which families must be enabled for your provider before anything is delivered, is in the Event catalog.

Webhook configuration

You configure where RCM should POST events when the subscription is created:

• One or more URLs per environment (sandbox and production are independent).
• Each subscription declares its authentication mechanism — HMAC (default) or BASIC. See Authentication.
• You subscribe selectively to event types (subscribed_event_types), e.g. only validation events, no classification.
• Optional custom headers forwarded on every delivery.

See Authentication and the Webhook subscriptions API for how to register and manage a subscription.

Next steps

• Authentication — HMAC or Basic, and how to verify each.
• Event catalog — every event_type a subscription can receive, stable and preview.
• Verify signatures — required before processing the body (HMAC).
• Classification events — full payload spec.
• Validation events — full payload spec.
• Audit events — Orizon RGA audit outcomes, one event per item.
• Payload reference — all payload fields.