Manage Webhooks

Configure webhook callback URLs for receiving real-time notifications about payment and withdrawal events.

POST

/user/webhooks/

Set up or update the webhook callback URL for your account. On first setup, a new webhook secret is generated and returned in full. On subsequent updates, only the masked secret is returned.

Authentication

Requires OAuth 2.0 authentication with write scope.

Request Body

Parameter	Type	Required	Description
`callback_url`	string (URL)	Yes	The URL where webhook notifications will be sent

Example Request

curl -X POST {{BASE_URL}}/user/webhooks/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://example.com/crypto/webhook"
  }'

Response

First Setup Response (200 OK)

When setting up a webhook for the first time, the full secret is returned:

{
  "callback_url": "https://example.com/crypto/webhook",
  "secret": "whsk_6E8F92D4C7B31A5E9D0F87H2T",
  "message": "Webhook configured successfully. Store the secret securely - it will not be shown again."
}

Update Response (200 OK)

When updating an existing webhook URL, only the masked secret is returned:

{
  "callback_url": "https://example.com/crypto/webhook-v2",
  "masked_secret": "whsk_6E****************************hT",
  "message": "Webhook URL updated successfully."
}

Response Fields

Field	Type	Description
`callback_url`	string	The configured webhook callback URL
`secret`	string	Full webhook secret for signature verification (only on first setup)
`masked_secret`	string	Partially masked webhook secret (on subsequent updates)
`message`	string	Confirmation message

Error Responses

400 Bad Request

{
  "error": {
    "code": "invalid_url",
    "message": "The provided callback URL is not valid",
    "details": {}
  }
}

401 Unauthorized

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or missing authentication token",
    "details": {}
  }
}

403 Forbidden

{
  "error": {
    "code": "permission_denied",
    "message": "Token does not have required scope",
    "details": {
      "required_scopes": ["write"],
      "token_scopes": ["read"]
    }
  }
}

Usage Examples

Setting Up a Webhook

async function setupWebhook(callbackUrl, accessToken) {
  const response = await fetch('{{BASE_URL}}/user/webhooks/', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      callback_url: callbackUrl
    })
  });

  const data = await response.json();

  if (data.secret) {
    // First setup - store the secret securely
    console.log('Webhook secret (store this!):', data.secret);
  } else {
    console.log('Webhook URL updated');
    console.log('Existing secret:', data.masked_secret);
  }

  return data;
}

Python Example

import requests

def configure_webhook(callback_url, access_token):
    """Configure or update webhook callback URL."""

    response = requests.post(
        '{{BASE_URL}}/user/webhooks/',
        json={'callback_url': callback_url},
        headers={'Authorization': f'Bearer {access_token}'}
    )

    if response.status_code == 200:
        data = response.json()
        print(f"Callback URL: {data['callback_url']}")
        print(f"Message: {data['message']}")

        if 'secret' in data:
            print(f"Secret (save this!): {data['secret']}")
        else:
            print(f"Masked secret: {data['masked_secret']}")

        return data
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None

Important Notes

The webhook secret is only shown in full during first setup. Store it securely.
Webhook notifications are sent as HTTP POST requests with a JSON payload.
Each request includes a signature in the X-Signature header for verification using your webhook secret.
Webhook deliveries are retried with exponential backoff in case of failure.