Skip to main content

​
Overview

Webhooks let your system receive real-time notifications about events happening in CryptoMate — new deposits, card authorizations, withdrawals, and more. Notifications are delivered to an HTTP endpoint you configure in your environment.

​
Webhook payload structure

Every webhook request shares a common envelope and an event-specific data object.
FieldTypeDescription
operationstringHigh-level operation type (e.g. TREASURY, CARDS, VIRTUAL_WALLETS)
sub_operationstringSpecific activity within the operation
operation_idstringUnique identifier for this notification
statusstringSUCCESS | CANCELLED | FAILED
reasonstringFailure reason (present when status is FAILED)
dataobjectEvent-specific payload; shape varies by event type

​
Example

{
  "operation": "TREASURY",
  "sub_operation": "DEPOSIT",
  "operation_id": "ca0c57d2-b1c9-4bcd-9d5d-8d361cad6fdd",
  "status": "SUCCESS",
  "data": { }
}

​
Available events

  • New deposit received
  • Card transaction approval
  • Card transaction declined
  • Card transaction clearing pending
  • Card transaction clearing failed
  • Card transaction cleared
  • Card transaction refund
  • Card transaction reversal
  • Card 3DS challenge
  • Withdraw completed

​
Setup

To start receiving notifications, configure a webhook endpoint capable of receiving and processing the payloads above.
1

Expose an HTTPS endpoint

Host a publicly reachable HTTPS URL that accepts POST requests with a JSON body.
2

Register it in CryptoMate

Register the endpoint from the Portal so CryptoMate knows where to deliver events.
3

Acknowledge quickly

Return a 2xx response as soon as you’ve persisted the event. Do heavier processing asynchronously to avoid timeouts.
4

Handle retries idempotently

Use operation_id to deduplicate events — the same webhook may be delivered more than once if your endpoint doesn’t respond in time.
For card transaction authorization, your endpoint has 1,200 ms to respond with an approval or rejection before CryptoMate applies the default behavior.