Register Webhook
Register a new webhook endpoint to receive event notifications from Payward.
When you register a webhook, you’ll receive a signing_secret in the response. This secret
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 must specify at least one event when registering a webhook. You can optionally set disabled to create the webhook without sending events immediately.
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/webhookhttps://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)
Authorizations
Your public API key. Identifies the partner making the request.
Monotonically increasing nonce included in the request signature.
HMAC signature over the request, computed with your private key.
Headers
Client-generated UUIDv4 for safe retries. Sent as the Idempotency-Key HTTP header. Replayed responses include the Idempotent-Replayed: true header.
^[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}$"550e8400-e29b-41d4-a716-446655440000"
Body
The HTTPS URL where webhook events will be sent. This endpoint must be publicly accessible and respond to POST requests.
2048"https://your-domain.com/webhooks/payward"
List of event types to subscribe to. At least one event is required.
1 - 100 elementsquote.executed, quote.cancelled, quote.execution_failed, user.closed, user.disabled, user.verified, user.verification_failed, user.verification_needed, conversion.deposit_completed, conversion.deposit_failed, conversion.deposit_held, conversion.quote_execution_failed, conversion.withdrawal_completed, conversion.withdrawal_failed Optional free-form label for the webhook.
500"primary delivery"
Create the webhook in a disabled state. Defaults to false.
false
Response
Webhook registered successfully