Overview
Payout webhooks allow Payviox to send real-time HTTP POST notifications to your server when payout status changes occur. This enables you to keep your application synchronized with payout statuses without polling the API.Payout webhooks use a separate URL and secret token from payment webhooks. Configure your payout webhook URL in the Payviox Dashboard under Payout > Webhooks.
Configuration
Create Your Endpoint
Create an endpoint on your server to receive POST requests (e.g.,
https://yourdomain.com/api/payout-webhook)Add URL to Dashboard
Go to your Payviox Dashboard and navigate to Payout > Webhooks
Save Your Payout Webhook Token
Copy your payout webhook token - you’ll need it to verify webhook signatures
Select Payout Events
Choose which payout events you want to receive. By default, only
payout.succeeded is enabled.Available Events
You can subscribe to the following payout webhook events:| Event | Description | Recommended Action |
|---|---|---|
payout.created | Payout order has been created | Update status to “processing” |
payout.processing | Payout is being sent | Inform the recipient that the payout is on its way |
payout.succeeded | Payout confirmed and delivered | Confirm delivery to the recipient |
payout.failed | Payout failed | Contact support or retry |
payout.rejected | Payout was rejected | Inform the recipient of the rejection |
Payload Structure
All payout webhooks follow the same root layout: amounts,metadata, type, provider, your internal order_id, recipient, and exactly one extra object whose JSON key matches provider (paypal, crypto, or any future rail). That object carries provider-specific identifiers and details only—no duplicate amounts.
Some event types add optional root fields (e.g. reason on payout.rejected when an admin note exists). Omitted fields are not sent.
Reference payload
Example forpayout.succeeded with provider paypal:
Same pattern, `provider`: `crypto`
Same pattern, `provider`: `crypto`
The
crypto object replaces paypal. Field set may evolve with the rail; amounts stay on the root.Event `payout.rejected` + optional `reason`
Event `payout.rejected` + optional `reason`
When a payout is rejected (e.g. PayPal manual review),
type is payout.rejected. reason is included only if the operator entered a note (same text as in the dashboard).Payload Fields
The payout amount in the smallest currency unit (e.g., cents for USD)
Three-letter ISO currency code (always
USD for payouts)Fees amount in the smallest currency unit. Omitted if zero.
Amount after fees in the smallest currency unit. Omitted if equal to
amount.Metadata associated with the payout
The payout event type. Possible values:
payout.created: Payout order has been created.payout.processing: Payout is being sent.payout.succeeded: Payout confirmed and delivered.payout.failed: Payout failed.payout.rejected: Payout was rejected.
Only on
payout.rejected. Human-readable rejection note entered by the admin (PayPal payouts). Omitted if no note was provided.The payout provider:
"paypal" or "crypto"Payviox internal order identifier
Recipient information
PayPal-specific details. Only present when
provider is "paypal".Crypto-specific details. Only present when
provider is "crypto".Only present on test webhooks sent from the dashboard. Always
true when present.Webhook Headers
Every payout webhook request includes these headers:| Header | Description |
|---|---|
Content-Type | Always application/json |
Signature | HMAC SHA256 signature for verification |
Signature Verification
TheSignature header contains an HMAC SHA256 hash of the request body, signed with your payout webhook token (not the payment webhook token).
Verification Algorithm
- Get the raw request body (JSON string)
- Compute HMAC SHA256 hash using your payout webhook token as the secret key
- Compare the computed signature with the
Signatureheader - Only process the webhook if signatures match
Implementation Examples
Retry Logic
Payviox implements an automatic retry mechanism for failed payout webhook deliveries:After 4 failed attempts, the webhook will be marked as failed. You can manually retry failed webhooks from the Payviox Dashboard under Payout > Webhook Logs.
Success Criteria
A webhook is considered successfully delivered when your endpoint:- Returns HTTP status code
200 - Responds within 30 seconds
Testing
You can send a test payout webhook from the dashboard to verify your integration:- Go to Payout > Webhooks in the dashboard
- Click Send Test Webhook
- Select the event type to test
- The test payload will include
"test_mode": true
Test webhooks use the same signature mechanism as production webhooks. Use them to verify your signature verification logic.
Best Practices
Troubleshooting
Signature Verification Failing
Signature Verification Failing
Possible causes:
- Using the payment webhook token instead of the payout webhook token
- Parsing/modifying the request body before verification
- Incorrect HMAC algorithm (must be SHA256)
Webhooks Not Being Received
Webhooks Not Being Received
Possible causes:
- Payout webhooks are not enabled (toggle is off)
- Incorrect payout webhook URL in dashboard
- Not subscribed to the event type
- Firewall blocking Payviox IP addresses
Duplicate Webhook Processing
Duplicate Webhook Processing
Possible causes:
- Not implementing idempotency checks
- Slow response times causing retries
order_id + type as a unique key. Respond quickly with 200 OK and process asynchronously.Webhook Timeout
Webhook Timeout
Possible causes:
- Processing taking too long before responding
- Database locks or slow queries
Need Help?
If you’re having trouble with payout webhook integration:- Check the Payout Webhook Logs in your dashboard
- Review your server logs for errors
- Contact support@payviox.com for assistance