Overview

Reap sends HTTP POST requests to your endpoint whenever resources change. Use webhooks to stay in sync without polling.

Setup

Register an endpoint by calling Create a webhook endpoint with a name and an HTTPS url. The response includes a signingSecret returned exactly once. Store it securely. Reap does not retain a copy, and there is no way to read it back later.

{
  "name": "production-events",
  "url": "https://api.example.com/webhooks/reap"
}

You can register up to 5 active endpoints per project. Every event type is delivered to every active endpoint. To stop deliveries to an endpoint, call Disable a webhook endpoint. Disabling is one-way, so create a new endpoint if you need to resume delivery to the same URL. To rotate a signing secret (for example if the previous value leaked), call Rotate the signing secret. The old secret is invalidated immediately. Update your verifier with the new value before the next event arrives, or in-flight deliveries will fail HMAC verification on your endpoint and be retried automatically. Your endpoint must return a 2xx status code to acknowledge each delivery. Non-2xx responses or timeouts trigger automatic retries with exponential backoff over approximately 48 hours.

Source IP addresses

Webhook deliveries originate from a fixed set of egress IP addresses per environment. If your endpoint sits behind a firewall or allowlist, permit inbound traffic from all of the addresses for the environment you integrate with.

Environment	Egress IP addresses
Sandbox	`13.228.84.42/32`
Production	`13.251.96.90/32`, `13.229.17.218/32`, `3.1.46.185/32`

Allowlist every address listed for your environment. These addresses are stable, but we will notify you in advance if they ever change.

Event envelope

Every delivery wraps event data in a standard envelope:

{
  "id": "evt_01J5K7Q8R9T0V1W2X3Y4Z5A6B7",
  "type": "CRYPTO_DEPOSIT_CREATED",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "chainId": "BASE",
    "status": "PENDING",
    "amount": "100.00"
  }
}

Field	Type	Description
`id`	`string`	Unique event ID. Use for idempotency.
`type`	`string`	Event type, e.g. `CRYPTO_DEPOSIT_CREATED`.
`data`	`object`	Payload matching the corresponding API resource.

HTTP headers

Header	Description
`X-Reap-Webhook-Id`	Unique event ID (same as `id` in the body).
`X-Reap-Webhook-Timestamp`	Unix timestamp (seconds) of signature generation.
`X-Reap-Webhook-Signature`	HMAC-SHA256 signature. See Signature Verification.
`Content-Type`	Always `application/json`.

Event types

Event	Description
`USER_APPLICATION_STATUS_UPDATED`	User application status changed (KYC approval, rejection, etc.)
`COMPANY_STATUS_UPDATED`	Company status changed (KYB approval, rejection, etc.)
`CRYPTO_DEPOSIT_CREATED`	New on-chain deposit detected
`CRYPTO_DEPOSIT_STATUS_UPDATED`	Deposit status changed (approved, rejected, etc.)
`CARD_STATUS_UPDATED`	Card status changed (activated, frozen, blocked, etc.)
`ACCOUNT_STATUS_UPDATED`	Account status changed (restricted, reactivated, etc.)
`CARD_TRANSACTION_CREATED`	New card transaction
`CARD_TRANSACTION_UPDATED`	Card transaction lifecycle event (clearing, reversal, refund, etc.)
`CARD_3DS_CHALLENGE_CREATED`	3DS challenge created for a cardholder (see 3D Secure)
`CARD_SHIPMENT_STATUS_UPDATED`	Physical card shipment status changed
`CARD_TOKENIZATION_REQUESTED`	OTP for adding a card to a digital wallet via SMS verification (valid for a short window)

Payloads match the shape of the corresponding API resource. For example, CRYPTO_DEPOSIT_CREATED data matches GET /crypto-deposits/:id.

Best practices

Return quickly. Respond with 2xx within a few seconds. Process heavy work in the background.
Be idempotent. Events may be delivered more than once. Use the id field to skip duplicates.
Verify signatures. Always verify the signature before processing.

Webhooks

Event Types

Setup

Source IP addresses

Event envelope

HTTP headers

Event types

Best practices

​Setup

​Source IP addresses

​Event envelope

​HTTP headers

​Event types

​Best practices

Setup

Source IP addresses

Event envelope

HTTP headers

Event types

Best practices