Manage Webhooks

GET

/user/webhooks

Retrieves all webhook configurations for the account. Webhooks allow you to receive real-time notifications about events such as payment confirmations, withdrawal status changes, and security events.

Example Request

GET /user/webhooks
X-API-Key: your_api_key_here

Response Parameters

Parameter	Type	Description
webhooks	array	List of webhook configurations
count	number	Total number of webhook configurations

Webhook Object

Parameter	Type	Description
id	string	Unique identifier for the webhook
url	string	The URL where webhook notifications are sent
event_types	array	Array of event types this webhook will receive
status	string	"active" or "inactive"
created_at	string	ISO 8601 timestamp of when the webhook was created
last_triggered_at	string	ISO 8601 timestamp of when the webhook was last triggered
failure_count	number	Number of consecutive failed delivery attempts
secret	string	Partially redacted secret key used for webhook signature verification

Example Response

{
  "webhooks": [
    {
      "id": "wh_550e8400e29b41d4a716446655440000",
      "url": "https://example.com/crypto/webhook",
      "event_types": [
        "payment.completed",
        "payment.failed",
        "withdrawal.status_changed"
      ],
      "status": "active",
      "created_at": "2025-03-15T12:30:45.123Z",
      "last_triggered_at": "2025-04-30T14:22:33.456Z",
      "failure_count": 0,
      "secret": "whsk_6E****************************hT"
    },
    {
      "id": "wh_98765432abcdef0123456789abcdef01",
      "url": "https://backup.example.com/webhooks",
      "event_types": [
        "payment.all",
        "withdrawal.all",
        "security.all"
      ],
      "status": "inactive",
      "created_at": "2025-04-01T09:15:30.789Z",
      "last_triggered_at": null,
      "failure_count": 3,
      "secret": "whsk_7A****************************dZ"
    }
  ],
  "count": 2
}

Error Codes

Status Code	Error Code	Description
401	authentication_failed	Authentication failed. Check your API key or OAuth 2.0 access token
403	insufficient_permissions	Your API key does not have permission to manage webhooks
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint

POST

/user/webhooks

Creates a new webhook configuration. The webhook will receive notifications for the specified event types.

Request Parameters

Parameter	Type	Description
url required	string	The URL where webhook notifications will be sent (must be HTTPS)
event_types optional	array	Array of event types to subscribe to (defaults to all events if not specified)
description optional	string	Description of the webhook for your reference

Example Request

POST /user/webhooks
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "url": "https://example.com/crypto/webhook",
  "event_types": [
    "payment.completed",
    "payment.failed",
    "withdrawal.status_changed"
  ],
  "description": "Main payment notifications webhook"
}

Response Parameters

Parameter	Type	Description
id	string	Unique identifier for the newly created webhook
url	string	The URL where webhook notifications will be sent
event_types	array	Array of event types this webhook will receive
status	string	"active" by default for new webhooks
created_at	string	ISO 8601 timestamp of when the webhook was created
secret	string	Secret key for webhook signature verification (shown only once during creation)
description	string	Description of the webhook

Example Response

{
  "id": "wh_550e8400e29b41d4a716446655440000",
  "url": "https://example.com/crypto/webhook",
  "event_types": [
    "payment.completed",
    "payment.failed",
    "withdrawal.status_changed"
  ],
  "status": "active",
  "created_at": "2025-04-30T16:22:33.456Z",
  "secret": "whsk_6E8F92D4C7B31A5E9D0F87H2T",
  "description": "Main payment notifications webhook"
}

Error Codes

Status Code	Error Code	Description
400	invalid_url	The URL is invalid or doesn't use HTTPS
400	invalid_event_types	One or more event types are invalid
400	url_already_exists	A webhook with this URL already exists
401	authentication_failed	Authentication failed. Check your API key or OAuth 2.0 access token
403	insufficient_permissions	Your API key does not have permission to manage webhooks
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint

DELETE

/user/webhooks

Deletes a webhook configuration. Once deleted, notifications will no longer be sent to the URL associated with the webhook.

Request Parameters

Parameter	Type	Description
webhook_id required	string	The ID of the webhook to delete

Example Request

DELETE /user/webhooks
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "webhook_id": "wh_550e8400e29b41d4a716446655440000"
}

Response Parameters

Parameter	Type	Description
deleted	boolean	True if the webhook was successfully deleted
webhook_id	string	The ID of the deleted webhook

Example Response

{
  "deleted": true,
  "webhook_id": "wh_550e8400e29b41d4a716446655440000"
}

Error Codes

Status Code	Error Code	Description
400	invalid_webhook_id	The webhook ID is invalid
404	webhook_not_found	No webhook with the specified ID was found
401	authentication_failed	Authentication failed. Check your API key or OAuth 2.0 access token
403	insufficient_permissions	Your API key does not have permission to manage webhooks
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint

Webhook Event Types

Event Type	Description
payment.created	A new payment has been created
payment.processing	A payment is being processed (transaction detected on blockchain)
payment.completed	A payment has been completed successfully
payment.failed	A payment has failed
payment.expired	A payment has expired without being completed
payment.all	All payment-related events
withdrawal.created	A new withdrawal has been created
withdrawal.approved	A withdrawal has been approved
withdrawal.processing	A withdrawal is being processed
withdrawal.completed	A withdrawal has been completed successfully
withdrawal.failed	A withdrawal has failed
withdrawal.cancelled	A withdrawal has been cancelled
withdrawal.status_changed	Any change to a withdrawal's status
withdrawal.all	All withdrawal-related events
wallet.created	A new wallet has been created
wallet.balance_changed	A wallet's balance has changed
wallet.all	All wallet-related events
security.login_attempt	A login attempt has been detected
security.settings_changed	Security settings have been changed
security.all	All security-related events

Webhook Payload Format

All webhooks are sent as HTTP POST requests with a JSON payload containing the following fields:

Parameter	Type	Description
id	string	Unique identifier for this webhook notification
event	string	The type of event that triggered the webhook
created_at	string	ISO 8601 timestamp of when the event occurred
data	object	The data associated with the event (varies by event type)

Notes

Webhooks are only sent to HTTPS URLs for security reasons.
Each webhook request includes a signature in the X-Signature header for verification.
Webhook deliveries are retried up to 5 times with exponential backoff in case of failure.
After 5 consecutive failures, a webhook is automatically set to "inactive" status.
You can create up to 10 webhooks per account.
The secret key for verifying webhook signatures is only shown once during creation.
Keep the secret key secure and never expose it in client-side code.

iGaming Integration Note

For online casino platforms, webhook integration is crucial for maintaining accurate player balances. Configure webhooks to track all payment.completed and withdrawal.completed events to update player balances in real-time. Set up redundant webhook endpoints to ensure no transaction notifications are missed. For high-volume casinos, consider implementing separate webhooks for deposits and withdrawals to manage the processing load more efficiently.