Skip to main content
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.

​
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"
  }
}
FieldTypeDescription
idstringUnique event ID. Use for idempotency.
typestringEvent type, e.g. CRYPTO_DEPOSIT_CREATED.
dataobjectPayload matching the corresponding API resource.

​
HTTP headers

HeaderDescription
X-Reap-Webhook-IdUnique event ID (same as id in the body).
X-Reap-Webhook-TimestampUnix timestamp (seconds) of signature generation.
X-Reap-Webhook-SignatureHMAC-SHA256 signature. See Signature Verification.
Content-TypeAlways application/json.

​
Event types

EventDescription
USER_APPLICATION_STATUS_UPDATEDUser application status changed (KYC approval, rejection, etc.)
COMPANY_STATUS_UPDATEDCompany status changed (KYB approval, rejection, etc.)
CRYPTO_DEPOSIT_CREATEDNew on-chain deposit detected
CRYPTO_DEPOSIT_STATUS_UPDATEDDeposit status changed (approved, rejected, etc.)
CARD_STATUS_UPDATEDCard status changed (activated, frozen, blocked, etc.)
ACCOUNT_STATUS_UPDATEDAccount status changed (restricted, reactivated, etc.)
CARD_TRANSACTION_CREATEDNew card transaction
CARD_TRANSACTION_UPDATEDCard transaction lifecycle event (clearing, reversal, refund, etc.)
CARD_3DS_CHALLENGE_CREATED3DS challenge created for a cardholder (see 3D Secure)
CARD_SHIPMENT_STATUS_UPDATEDPhysical card shipment status changed
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.