🛠️Webhook setup

Optional: This step is optional and by no means needed to get a functioning integration up and running. Setting up webhooks is a way for you to always know the status of a transaction.

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

1

Partner implements endpoint

Partner implements an HTTPS endpoint to receive webhook events.

2

Provide endpoint URL

Partner provides the endpoint URL to our team.

3

Register endpoint

We register the endpoint and generate a verification secret key.

4

Share secret

The secret key is shared with the partner.

5

Verify requests

Each webhook request is signed and can be verified by the partner.

---

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

{
  "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)

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.