Webhooks
Overview
Webhooks provide real-time notifications about events in your Yugo account. Instead of polling the API for status changes, Yugo will send HTTP POST requests to your configured webhook URL when events occur.
Events
Yugo sends webhook notifications for the following events:
- Payin Status Changed
- Payout Status Changed
Webhook Request Format
Headers
Each webhook request includes the following headers:
POST /your-webhook-endpoint
Host: your-domain.com
Content-Type: application/json
X-API-Key: your_api_key
Authentication: Webhooks include your API key in the X-API-Key header. Verify this header matches your API key to ensure the request is from Yugo.
Payload
The request body contains the complete resource object (Payin or Payout) in JSON format.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"reference": "ORDER-12345",
"status": "AUTHORIZED",
// ...
}
Implementing a Webhook Endpoint
Basic Requirements
Your webhook endpoint must:
- Accept POST requests - Yugo sends all webhooks as HTTP POST
- Return 200 OK - Respond with status code 200-299 to acknowledge receipt
- Respond quickly - Return a response within 1 second
- Be publicly accessible - The URL must be reachable from the internet
- Use HTTPS - Webhook URLs must use HTTPS in production
- Be idempotent - Handle duplicate webhook deliveries gracefully
- Verify the secret - Validate the API Key passed in the header
- Be whitelisted - Add your endpoint URL in the Yugo Merchant Portal
Retry Behavior
When Yugo Retries
Yugo automatically retries webhook delivery when:
- Your endpoint returns a 4xx or 5xx status code
- Your endpoint doesn't respond within 5 seconds (timeout)
- There's a network error preventing delivery
Retry Schedule
Yugo uses exponential backoff for up to 48 hours.
You can query the resource via the API to get the current status.
Common Issues
Issue: Webhooks Not Received
Possible Causes:
- Webhook URL is not publicly accessible
- Firewall blocking Yugo's IP addresses
- SSL certificate issues (expired, self-signed)
- Endpoint returning non-2xx status code
Solution:
- Test your webhook URL with
curlfrom an external server - Check firewall and security group settings
- Verify SSL certificate is valid
- Check application logs for errors
Issue: Duplicate Webhooks
Possible Cause: Your endpoint is slow to respond, causing timeouts and retries.
Solution:
- Acknowledge webhooks immediately (return 200 OK)
- Process events asynchronously in background jobs
- Implement idempotency checks
FAQ
Q: Can I use the same webhook URL for multiple events?
Yes. Your endpoint will receive all event types at the same URL. Inspect the payload structure to determine the event type.
Q: What if my webhook endpoint is down during an event?
Yugo will retry delivery multiple times. If your endpoint is down longer, you can still query the API to get the current resource status.
Q: Can I change my webhook URL?
Yes. Update the webhook_url field when creating new Payins/Payouts. The webhook URL is set per resource, not account-wide.
Q: How do I test webhooks without creating real payments?
Use the sandbox environment with test API keys. All sandbox resources trigger real webhooks to your configured endpoint.