Skip to main content
WEBHOOK

Authorizations

Authorization
string
header
required

Merchant authentication token. Obtained via POST /api/v1/merchant/token/grant. Pass as: Authorization: Bearer

Headers

CrowdSplit-Signature
string
required

HMAC-SHA256 signature over the raw request body, signed with the merchant's webhook secret. Format: t={unix-ts},v1={hex-hmac}.

Example:

"t=1713456789,v1=a1b2c3d4e5f6abcdef1234567890abcdef1234567890abcdef1234567890abcd"

CrowdSplit-Timestamp
integer
required

Unix timestamp (seconds since epoch) at dispatch. Merchants should reject the delivery if the skew against their own clock exceeds 5 minutes, to limit replay windows.

Example:

1713456789

CrowdSplit-Notification-Id
string<uuid>
required

Unique delivery ID. Stable across retries of the same logical event — use it to deduplicate idempotently on receipt.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Body

application/json

Base envelope delivered to merchant webhook endpoints. Every webhook request body has the shape { id, api_version, event, category, data }; concrete event schemas compose this base via allOf and refine event / category to their const values and data to a specific schema.

Each delivery carries three headers: CrowdSplit-Signature t={unix-ts},v1={hex-hmac-sha256} CrowdSplit-Timestamp seconds since epoch CrowdSplit-Notification-Id unique per delivery (idempotency)

Merchants MUST verify the HMAC of the raw body using the webhook secret returned at registration, and SHOULD reject the delivery if CrowdSplit-Timestamp differs from the current time by more than 5 minutes. Duplicate CrowdSplit-Notification-Id values indicate a retry of a previously dispatched delivery and should be deduplicated.

id
string<uuid>
required

Unique notification ID (stable across retry attempts).

api_version
string
required

API version of the payload builder that produced this event (currently always v1). Reports the version of the code that built data — not a globally-bumped number — so when one event type later moves to v2, only that event reports v2. Branch on this field if you need to handle multiple payload shapes for the same event.

Pattern: ^v[0-9]+$
Example:

"v1"

event
string
required

Event name; specialized via allOf per operation (e.g. payment.succeeded).

Allowed value: "payment.dispute.funds_reinstated"
category
string
required

Event category; specialized via allOf per operation (e.g. payment_lifecycle).

Allowed value: "dispute_lifecycle"
data
object
required

Data payload for dispute events

Response

200

Webhook acknowledged