Register Webhook

Register a new webhook endpoint to receive event notifications from Payward Embed.

When you register a webhook, you’ll receive a secret in the response. This secret is base64-encoded and is used to verify webhook signatures. Store it securely — it is only returned once and cannot be retrieved again.

Before registering a webhook, make sure your callback domain has been allowlisted.

You can optionally specify enabled and events at registration time, or configure them later using the Update Webhook endpoint.

URL Requirements

• Must use HTTPS protocol
• Maximum length: 2048 characters
• Must be a valid URL format
• Must have a valid host (not empty)
• Host cannot be a protocol name (e.g., http, https, ftp, file, mailto, ssh, git, svn)
• Path cannot start with // (indicates malformed URL)
• Cannot contain credentials (e.g., https://user:[e-mail] is rejected)

Valid URL Examples

• https://example.com/webhook
• https://example.com:8443/webhook

Invalid URL Examples

• http://example.com/webhook (HTTP not allowed)
• https://https//example.com (malformed - host is “https”)
• https://user:[e-mail]/webhook (credentials not allowed)
• invalid-url (not a valid URL)

POST /b2b/webhooks

Register Webhook

cURL

curl --request POST \
  --url https://nexus.kraken.com/b2b/webhooks \
  --header 'API-Key: <api-key>' \
  --header 'API-Sign: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://your-domain.com/webhooks/payward",
  "enabled": true,
  "events": [
    "quote.executed"
  ]
}
'

200

{
  "result": {
    "webhook": {
      "id": "WHTEST-XXXXX-EXAMPLE",
      "url": "https://your-domain.com/webhooks/payward",
      "enabled": false,
      "subscribed_events": [],
      "available_events": [
        "custom_order.executed",
        "custom_order.execution_failed",
        "custom_order.cancelled",
        "quote.executed",
        "quote.execution_failed",
        "quote.cancelled",
        "reward.paid",
        "user.verified",
        "user.closed",
        "user.disabled",
        "deposit.status_updated",
        "withdrawal.status_updated"
      ],
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "secret": "dGVzdC1zZWNyZXQtcGxlYXNlLWlnbm9yZQ=="
  }
}

Authorizations

API-Key · string · header · required

The "API-Key" header should contain your API key.

API-Sign · string · header · required

Authenticated requests should be signed with the "API-Sign" header, using a signature generated with your private key, nonce, encoded payload, and URI path.

Headers

Payward-Version · enum<string> · default: 2025-04-15

The target version of the Embed API to use. The API version name is based on the date when the API version was released. For example, the API version 2025-04-15 was released on April 15, 2025.

Available options: 2025-04-15

Body

application/json

url · string<uri> · required

The HTTPS URL where webhook events will be sent. This endpoint must be publicly accessible and respond to POST requests.

Maximum string length: 2048

Example:

"https://your-domain.com/webhooks/payward"

enabled · boolean · default: false

Whether the webhook is enabled. Defaults to false. Disabled webhooks will not receive any events until enabled.

Example:

true

events · string[]

List of event types to subscribe to. Defaults to [] (no events). Use this to configure which events trigger webhook notifications.

Maximum array length: 50

Maximum string length: 100

Pattern: ^[a-zA-Z0-9._]+$

Example:

["quote.executed"]

Response

200

application/json

Webhook registered successfully

result · object

Show child attributes