# Webhook setup

## Overview

This guide explains how to set up and verify webhooks for receiving real-time transaction updates from our platform.

Webhooks allow partners to automatically receive notifications about transaction events on their backend systems.

***

## Integration Flow

{% stepper %}
{% step %}

### Partner implements endpoint

Partner implements an HTTPS endpoint to receive webhook events.
{% endstep %}

{% step %}

### Provide endpoint URL

Partner provides the endpoint URL to our team.
{% endstep %}

{% step %}

### Register endpoint

We register the endpoint and generate a verification secret key.
{% endstep %}

{% step %}

### Share secret

The secret key is shared with the partner.
{% endstep %}

{% step %}

### Verify requests

Each webhook request is signed and can be verified by the partner.
{% endstep %}
{% endstepper %}

***

## Webhook Endpoint Requirements

* HTTPS endpoint
* Accepts `POST` requests
* Accepts `application/json`
* Returns HTTP `200 OK` on successful receipt

***

## Webhook Payload Structure

Webhook events are delivered as JSON payloads in the request body.

### Example Payload

```json
{
  "event_id": "44cc910c-b0c1-4115-8b9c-a78eeacfbd3a",
  "timestamp": 1765290248,
  "transaction": {
    "created_at": "2025-06-03T12:54:22+00:00",
    "cryptocurrency": {
      "id": 1676,
      "logo": "/static/cryptocurrency/coin_default_image.png",
      "name": "bsc-usd",
      "symbol": "BSC-USD"
    },
    "cryptocurrency_amount": "0.00046945",
    "currency": {
      "full_name": "",
      "icon": "https://example.com/media/currencies/icons/USD.png",
      "id": 3,
      "name": "USD",
      "symbol": "$"
    },
    "currency_amount": "50.00000000000000000000",
    "kind": "buy",
    "network": {
      "code": "binance_smart_chain",
      "icon": null,
      "id": 238,
      "name": "binance_smart_chain",
      "network_compatibility_id": "",
      "protocol_standard": "",
      "regex": ""
    },
    "network_fee": null,
    "network_transaction_id": null,
    "payment_method": {
      "category": "Mobile Wallets",
      "category_code": "mobile_wallets",
      "category_description": "Instant payment",
      "category_display_name": "Mobile wallets",
      "category_icon": "https://example.com/static/service_integration/categories_pm/apple_pay.png",
      "code": "mobile_wallet",
      "icon": "https://example.com/media/service_integration/PaymentMethod/mobile_wallet_ios.png",
      "id": 5,
      "name": "Apple Pay"
    },
    "processing_fee": null,
    "raw_status": "completed",
    "region": {
      "alpha2_code": "GB",
      "alpha3_code": "GBR",
      "icon": "https://example.com/media/service_integration/Region/GB.png",
      "id": 154,
      "kind": "country",
      "name": "United Kingdom",
      "parent_region": null
    },
    "service": {
      "domain": "app.ramp.network",
      "icon": "https://example.com/media/service_integration/Service/ramp.png",
      "id": 3,
      "name": "Ramp",
      "privacy": "https://ramp.network/terms-of-service",
      "sell_available": false,
      "slug_name": "ramp",
      "terms": "https://ramp.network/privacy-policy",
      "url_for_support": "",
      "url_for_transaction_details": ""
    },
    "service_transaction_id": "sh55xez8f28fkpb",
    "status": "completed",
    "total_fee": null,
    "transaction_id": "fb352131-473d-4539-992d-49fadc73feac",
    "updated_at": "2025-12-09T14:24:08+00:00",
    "wallet_address": "tb1qms88luzzymwftjf9aht3xmdkw5j56tktfk57yd"
  }
}
```

***

## Top-Level Fields

| Field         | Type      | Description                |
| ------------- | --------- | -------------------------- |
| `event_id`    | `string`  | Unique webhook event ID    |
| `timestamp`   | `integer` | Webhook event timestamp    |
| `transaction` | `object`  | Transaction payload object |

***

## Transaction Object

The `transaction` object contains detailed information about the transaction.

| Field                    | Type               | Description                                |
| ------------------------ | ------------------ | ------------------------------------------ |
| `created_at`             | `string`           | Transaction start date and time (ISO 8601) |
| `cryptocurrency`         | `object`           | Cryptocurrency details                     |
| `cryptocurrency_amount`  | `string`           | Cryptocurrency amount                      |
| `currency`               | `object`           | Fiat currency details                      |
| `currency_amount`        | `string`           | Fiat amount                                |
| `kind`                   | `string`           | Transaction type (`buy` / `sell`)          |
| `network`                | `object`           | Blockchain network details                 |
| `network_fee`            | `string` or `null` | Network fee                                |
| `network_transaction_id` | `string` or `null` | Blockchain transaction ID                  |
| `payment_method`         | `object`           | Payment method details                     |
| `processing_fee`         | `string` or `null` | Processing fee                             |
| `raw_status`             | `string`           | Raw provider status                        |
| `region`                 | `object`           | Region information                         |
| `service`                | `object`           | Service provider information               |
| `service_transaction_id` | `string`           | Provider transaction ID                    |
| `status`                 | `string`           | Normalized transaction status              |
| `total_fee`              | `string` or `null` | Total fee                                  |
| `transaction_id`         | `string`           | Platform transaction ID                    |
| `updated_at`             | `string`           | Last update timestamp (ISO 8601)           |
| `wallet_address`         | `string`           | Destination wallet address                 |

***

### Cryptocurrency Object

| Field    | Type      | Description                     |
| -------- | --------- | ------------------------------- |
| `id`     | `integer` | Cryptocurrency ID               |
| `logo`   | `string`  | Cryptocurrency icon URL or path |
| `name`   | `string`  | Cryptocurrency name             |
| `symbol` | `string`  | Cryptocurrency symbol           |

***

### Currency Object

| Field       | Type      | Description        |
| ----------- | --------- | ------------------ |
| `full_name` | `string`  | Currency full name |
| `icon`      | `string`  | Currency icon URL  |
| `id`        | `integer` | Currency ID        |
| `name`      | `string`  | Currency code      |
| `symbol`    | `string`  | Currency symbol    |

***

### Network Object

| Field                      | Type               | Description                                        |
| -------------------------- | ------------------ | -------------------------------------------------- |
| `code`                     | `string`           | Network code                                       |
| `icon`                     | `string` or `null` | Network icon URL                                   |
| `id`                       | `integer`          | Network ID                                         |
| `name`                     | `string`           | Network name                                       |
| `network_compatibility_id` | `string`           | Network compatibility identifier (e.g. `eip155:1`) |
| `protocol_standard`        | `string`           | Protocol standard (`ERC-20`, `BEP-20`, etc.)       |
| `regex`                    | `string`           | Regular expression for wallet address validation   |

***

### Payment Method Object

| Field                   | Type      | Description             |
| ----------------------- | --------- | ----------------------- |
| `category`              | `string`  | Payment method category |
| `category_code`         | `string`  | Category code           |
| `category_description`  | `string`  | Category description    |
| `category_display_name` | `string`  | Category display name   |
| `category_icon`         | `string`  | Category icon URL       |
| `code`                  | `string`  | Payment method code     |
| `icon`                  | `string`  | Payment method icon URL |
| `id`                    | `integer` | Payment method ID       |
| `name`                  | `string`  | Payment method name     |

***

### Region Object

| Field           | Type               | Description                  |
| --------------- | ------------------ | ---------------------------- |
| `alpha2_code`   | `string`           | ISO alpha-2 region code      |
| `alpha3_code`   | `string`           | ISO alpha-3 region code      |
| `icon`          | `string`           | Region icon URL              |
| `id`            | `integer`          | Region ID                    |
| `kind`          | `string`           | Region kind (e.g. `country`) |
| `name`          | `string`           | Region name                  |
| `parent_region` | `object` or `null` | Parent region object         |

***

### Service Object

| Field                         | Type      | Description                  |
| ----------------------------- | --------- | ---------------------------- |
| `domain`                      | `string`  | Service domain               |
| `icon`                        | `string`  | Service icon URL             |
| `id`                          | `integer` | Service ID                   |
| `name`                        | `string`  | Service name                 |
| `privacy`                     | `string`  | Service privacy policy URL   |
| `sell_available`              | `boolean` | Is sell flow available       |
| `slug_name`                   | `string`  | Unique service slug          |
| `terms`                       | `string`  | Service terms URL            |
| `url_for_support`             | `string`  | Service support URL          |
| `url_for_transaction_details` | `string`  | Base transaction details URL |

***

## Webhook Verification

Each webhook request is signed using a secret key created during endpoint registration.

### Authorization Header

The signature is sent in the HTTP header:

Authorization: .

Where:

* `timestamp` — Unix timestamp used when signing the request.
* `signature` — HMAC SHA-256 hash generated using the shared secret and the concatenation of `timestamp` and the raw request body.

### Signature Verification Example (Python)

```python
import hashlib
import hmac

signature_key = 'wh_test_7995798b65494289a8977ae2f60d3acc'

authorization_header = request.headers['Authorization']
timestamp, expected_signature = authorization_header.split('.')

body = request.body.decode('utf-8')

signature = hmac.new(
    signature_key.encode('utf-8'),
    f"{timestamp}.{body}".encode('utf-8'),
    digestmod=hashlib.sha256,
).hexdigest()

assert expected_signature == signature
```

If the calculated signature matches the provided signature, the webhook is valid.

***

## Best Practices

* Always verify webhook signatures before processing events.
* Respond with HTTP `200 OK` as soon as the event is accepted for processing.
* Use `event_id` for idempotent processing (avoid handling the same event twice).
* Log and monitor failed verification attempts for security analysis.

***

## Support

For integration support or additional questions, please contact our support team.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coindisco.gitbook.io/coindisco/api-integration/webhook-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.