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
1
Create Your Endpoint
Create an endpoint on your server to receive POST requests (e.g.,
https://yourdomain.com/api/payout-webhook)2
Add URL to Dashboard
Go to your Payviox Dashboard and navigate to Payout > Webhooks
3
Enter Your Payout Webhook URL
Paste your endpoint URL in the payout webhook URL field
4
Save Your Payout Webhook Token
Copy your payout webhook token - you’ll need it to verify webhook signatures
5
Select Payout Events
Choose which payout events you want to receive. By default, only
payout.succeeded is enabled.6
Enable Webhooks
Toggle the payout webhook switch to enable delivery.
Available Events
You can subscribe to the following payout webhook events:payout.reversed is the only event that can arrive after payout.succeeded. If you credit recipients as soon as a payout succeeds, handle this event to roll that credit back.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 and payout.reversed 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
integer
required
The payout amount in the smallest currency unit (e.g., cents for USD)
string
required
Three-letter ISO currency code (always
USD for payouts)integer
Fees amount in the smallest currency unit. Omitted if zero.
integer
Amount after fees in the smallest currency unit. Omitted if equal to
amount.object
required
Metadata associated with the payout
string
required
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.
string
Only on
payout.rejected. Human-readable rejection note entered by the admin (PayPal payouts). Omitted if no note was provided.string
required
The payout provider:
"paypal" or "crypto"string
required
Unique order identifier for this payout
object
required
Recipient information
object
PayPal-specific details. Only present when
provider is "paypal".object
Crypto-specific details. Only present when
provider is "crypto".boolean
Only present on test webhooks sent from the dashboard. Always
true when present.Webhook Headers
Every payout webhook request includes these headers: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:1
First Attempt
Instant delivery (0 seconds)
2
Second Attempt
30 seconds after first failure
3
Third Attempt
5 minutes after second failure
4
Fourth Attempt
30 minutes after third failure
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