How It Works
Setting Up Outgoing Webhooks
Create your endpoint
Create an HTTPS endpoint on your server to receive webhook events:
To verify signatures (next step) you need the raw, unparsed request body. Make sure your framework gives you access to it — see the verified handler below.
Register in Partnero
- Go to Program Settings → Webhooks
- Click Add Webhook
- Enter your endpoint URL
- Select which events to receive
- Save and copy the signing secret
Verify signatures
Every webhook request includes a signature in the
Signature header. It is an
HMAC-SHA256 hash of the raw request body, keyed with your webhook’s signing
secret (the signature value shown when you created the webhook, also returned by
the Webhooks API).Available Events
Partner Events
| Event | Description |
|---|---|
partner.created | New partner signs up or is created |
partner.updated | Partner information is updated |
partner.approved | Partner application is approved |
partner.rejected | Partner application is rejected |
partner.archived | Partner is archived |
partner.deleted | Partner is deleted |
Customer Events
| Event | Description |
|---|---|
customer.created | New customer is created |
customer.updated | Customer information is updated |
customer.deleted | Customer is deleted |
Transaction Events
| Event | Description |
|---|---|
transaction.created | New transaction is recorded |
transaction.updated | Transaction is updated |
transaction.deleted | Transaction is deleted (refund) |
Reward Events
| Event | Description |
|---|---|
reward.created | Commission/reward is created |
reward.approved | Reward is approved for payout |
reward.paid | Reward is marked as paid |
Webhook Payload
All webhooks share the same envelope. The event-specific fields are nested underdata:
| Field | Type | Description |
|---|---|---|
event | string | The event name (e.g. transaction.created) |
url | string | The destination URL the webhook was sent to |
webhook_key | string | The key of the webhook subscription that fired |
created_at | string | ISO 8601 timestamp of when the event was dispatched |
data | object | Event-specific payload (see below) |
Event-Specific Payloads
partner.created
partner.created
transaction.created
transaction.created
reward.approved
reward.approved
Handling Webhooks
Best Practices
Respond Quickly
Return a 2xx status within 5 seconds. Process data asynchronously.
Implement Idempotency
Handle duplicate deliveries by tracking processed event IDs.
Use HTTPS
Always use HTTPS endpoints in production.
Log Everything
Log all received webhooks for debugging and audit trails.
Handling Retries
Partnero retries failed webhooks with exponential backoff:| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
After 5 failed attempts, the webhook is marked as failed. Check your webhook logs in the Partnero dashboard.
Example: Processing Partner Signup
Testing Webhooks
Using the Dashboard
- Go to Program Settings → Webhooks
- Find your webhook and click Test
- Select an event type
- Click Send Test Webhook
Using ngrok for Local Development
Troubleshooting
Webhooks not arriving
Webhooks not arriving
- Verify your endpoint URL is correct and accessible
- Check your server logs for incoming requests
- Ensure your firewall allows requests from Partnero IPs
- Check the webhook logs in your Partnero dashboard
Signature verification failing
Signature verification failing
- Ensure you’re using the correct signing secret
- Verify you’re hashing the raw request body
- Check for any middleware modifying the request body
Duplicate webhooks received
Duplicate webhooks received
- Implement idempotency using event IDs
- Track processed webhooks in your database
- Return 200 status quickly to prevent retries
