Webhooks

Webhooks let your app receive asynchronous notifications when events happen in Hub. Use the endpoints below to register, list, and delete webhook subscriptions.

The Webhook Model

The webhook model includes the callback URL, subscribed events, and the secret used to verify webhook signatures.

POST/api/webhooks

Create Webhook

Registers a webhook to receive async notifications for events. Send Content-Type: application/json, x-api-key, and x-token on every request.

Authorizations

Name
x-api-key
Type
string (header)
Description
Required Project API key sent in x-api-key header.
Name
x-token
Type
string (header)
Description
Required Session token sent in x-token header.

Headers

Name
idempotency-key
Type
string (header)
Description
Required Unique key that makes POST requests idempotent.

Body

Name
url
Type
string
Description
Required Callback URL that will receive webhook events.
Name
events
Type
array
Description
Required Events to subscribe. Available options: transaction, withdraw, dispute.

Request

POST

/api/webhooks

curl --request POST \
  --url https://my.domain.io/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --header 'x-token: <api-key>' \
  --data '
{
  "url": "https://webhook.site/04330df4-31be-4e79-a1af-611fcde55555",
  "events": ["transaction", "withdraw", "dispute"]
}
'

Properties Response

Webhook created.

Name
code
Type
integer
Description
Status code of the response. Example: 201.
Name
content
Type
object
Description
Webhook details.
Name
content.magic_id
Type
string
Description
Webhook magic identifier.
Name
content.url
Type
string
Description
Webhook callback URL.
Name
content.secret
Type
string
Description
Secret used to sign webhook payloads.
Name
content.events
Type
array
Description
Subscribed events.
Name
content.active
Type
boolean
Description
Whether the webhook is active.
Name
content.created_at
Type
string (date-time)
Description
The date and time when the webhook was created.
Name
content.updated_at
Type
string (date-time)
Description
The date and time when the webhook was last updated.
Name
message
Type
string
Description
Response message.
Name
timestamp
Type
string (date-time)
Description
Response timestamp.

Response

{
  "code": 201,
  "content": {
    "magic_id": "wh_03UdoKvLNLHg",
    "url": "https://webhook.site/04330df4-31be-4e79-a1af-611fcde55555",
    "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
    "events": ["transaction", "withdraw", "dispute"],
    "active": true,
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Webhook created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

GET/api/webhooks

List Webhooks

Returns all registered webhooks. Send x-api-key and x-token on every request.

Authorizations

Name
x-api-key
Type
string (header)
Description
Required Project API key sent in x-api-key header.
Name
x-token
Type
string (header)
Description
Required Session token sent in x-token header.

Request

GET

/api/webhooks

curl --request GET \
  --url https://my.domain.io/api/webhooks \
  --header 'x-api-key: <api-key>' \
  --header 'x-token: <api-key>'

Properties Response

Webhooks listed.

Name
code
Type
integer
Description
Status code of the response. Example: 200.
Name
content
Type
object[]
Description
List of webhooks.
Name
content.magic_id
Type
string
Description
Webhook magic identifier.
Name
content.url
Type
string
Description
Webhook callback URL.
Name
content.secret
Type
string
Description
Secret used to sign webhook payloads.
Name
content.events
Type
array
Description
Subscribed events.
Name
content.active
Type
boolean
Description
Whether the webhook is active.
Name
content.created_at
Type
string (date-time)
Description
The date and time when the webhook was created.
Name
content.updated_at
Type
string (date-time)
Description
The date and time when the webhook was last updated.
Name
message
Type
string
Description
Response message.
Name
timestamp
Type
string (date-time)
Description
Response timestamp.

200

{
  "code": 200,
  "content": [
    {
      "magic_id": "wh_03UdoKvLNLHg",
      "url": "https://webhook.site/04330df4-31be-4e79-a1af-611fcde55555",
      "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
      "events": ["transaction", "withdraw", "dispute"],
      "active": true,
      "created_at": "2025-02-19T17:15:25.688Z",
      "updated_at": "2025-02-19T17:15:26.703Z"
    }
  ],
  "message": "Webhooks listed",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

DELETE/api/webhooks/{magic_id}

Delete Webhook

Deletes a webhook using its magic_id. Send x-api-key and x-token on every request.

Authorizations

Name
x-api-key
Type
string (header)
Description
Required Project API key sent in x-api-key header.
Name
x-token
Type
string (header)
Description
Required Session token sent in x-token header.

Path Parameters

Name
magic_id
Type
string
Description
Required Webhook magic identifier.

Request

DELETE

/api/webhooks/{magic_id}

curl --request DELETE \
  --url https://my.domain.io/api/webhooks/wh_03UdoKvLNLHg \
  --header 'x-api-key: <api-key>' \
  --header 'x-token: <api-key>'

Properties Response

Webhook deleted.

Name
code
Type
integer
Description
Status code of the response. Example: 200.
Name
message
Type
string
Description
Response message.
Name
timestamp
Type
string (date-time)
Description
Response timestamp.

200

{
  "code": 200,
  "message": "Webhook deleted",
  "timestamp": "2025-02-19T17:15:26.703Z"
}