Skip to main content
POST
/
api
/
v1
/
webhooks
/
subscriptions
curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/webhooks/subscriptions \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "target_url": "https://example.com/webhooks/hostpay",
    "events": [
        "deposit.completed",
        "payout.failed"
    ]
  }'

{
  "secret": "whsec_9f8e7d6c...",
  "subscription": {
    "id": "7c1d2e3f-...",
    "application_id": "2e35e07e-...",
    "target_url": "https://example.com/webhooks/hostpay",
    "events": ["deposit.completed", "payout.failed"],
    "active": true,
    "ip_allowlist": null,
    "payload_version": "2025-01",
    "secret_preview": "...k3Qz",
    "created_at": "2026-07-04T10:30:00Z",
    "updated_at": "2026-07-04T10:30:00Z"
  }
}
Creates a webhook subscription. Deliveries are signed — verify them with the returned secret and the SDK’s construct_event (see Webhook security).
The signing secret is returned only in this response. Store it securely — it cannot be retrieved again, only rotated.

​
Request Body

​
target_url
string
required
The HTTPS endpoint to deliver events to. Internal/private addresses are rejected.
​
events
string[]
required
The event types to subscribe to, e.g. ["deposit.completed", "payout.failed"].
​
description
string
An optional label for this subscription.
​
ip_allowlist
string[]
Optional list of source IPs allowed to receive deliveries.
​
payload_version
string
Payload schema version. Defaults to the current version.

​
Response

​
secret
string
The signing secret — shown once.
​
subscription
object
The created subscription (same shape as list subscriptions).
{
  "secret": "whsec_9f8e7d6c...",
  "subscription": {
    "id": "7c1d2e3f-...",
    "application_id": "2e35e07e-...",
    "target_url": "https://example.com/webhooks/hostpay",
    "events": ["deposit.completed", "payout.failed"],
    "active": true,
    "ip_allowlist": null,
    "payload_version": "2025-01",
    "secret_preview": "...k3Qz",
    "created_at": "2026-07-04T10:30:00Z",
    "updated_at": "2026-07-04T10:30:00Z"
  }
}

curl --request POST \
  --url https://hpay-api.host-sl.com/api/v1/webhooks/subscriptions \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "target_url": "https://example.com/webhooks/hostpay",
    "events": [
        "deposit.completed",
        "payout.failed"
    ]
  }'