curl

curl -X POST "https://api.services.payward.com/v1/webhooks" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/payward"
  }'

{
  "data": {
    "webhook": {
      "id": "whk_01J0M7C0Z9F8YX3GQH8E",
      "url": "https://example.com/webhooks/payward",
      "enabled": true,
      "subscribed_events": [
        "transfer.completed",
        "transfer.failed",
        "swap.completed"
      ],
      "available_events": [
        "transfer.completed",
        "transfer.failed",
        "swap.completed",
        "swap.failed",
        "deposit.completed",
        "withdrawal.completed",
        "withdrawal.failed"
      ],
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2026-04-22T08:14:32Z"
    },
    "secret": "whsec_5kQp9rYx1NbFeZv8mTcHw2sJ0aL3oU6dRgIqMnXyBwPjE7lT"
  }
}

Webhooks

Register Webhook

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:[email protected] 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:[email protected]/webhook (credentials not allowed)
invalid-url (not a valid URL)

POST

webhooks

curl

curl -X POST "https://api.services.payward.com/v1/webhooks" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/payward"
  }'

{
  "data": {
    "webhook": {
      "id": "whk_01J0M7C0Z9F8YX3GQH8E",
      "url": "https://example.com/webhooks/payward",
      "enabled": true,
      "subscribed_events": [
        "transfer.completed",
        "transfer.failed",
        "swap.completed"
      ],
      "available_events": [
        "transfer.completed",
        "transfer.failed",
        "swap.completed",
        "swap.failed",
        "deposit.completed",
        "withdrawal.completed",
        "withdrawal.failed"
      ],
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2026-04-22T08:14:32Z"
    },
    "secret": "whsec_5kQp9rYx1NbFeZv8mTcHw2sJ0aL3oU6dRgIqMnXyBwPjE7lT"
  }
}

Authorizations

API-Key

string

header

required

Your public API key. Identifies the partner making the request.

API-Nonce

string

header

required

Monotonically increasing nonce included in the request signature.

API-Sign

string

header

required

HMAC signature over the request, computed with your private key.

Headers

Idempotency-Key

string<uuid>

Client-generated UUIDv4 for safe retries. Sent as the Idempotency-Key HTTP header. Replayed responses include the Idempotent-Replayed: true header.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Example:

"550e8400-e29b-41d4-a716-446655440000"

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

Webhook registered successfully

data

object

required

Show child attributes

List Webhooks Delete Webhook

⌘I