Webhooks
Stop polling for changes. Webhooks push events to your systems the moment they happen – so your tools and team can react instantly.
Delivery Formats
Choose the format that matches your destination:
- Raw JSON sends the complete machine-readable Affonso event to your application. Raw JSON requests are signed with your endpoint secret.
- Slack sends a concise, readable notification to a Slack incoming-webhook URL.
- Discord sends a concise, readable notification to a Discord incoming-webhook URL.
Slack and Discord use incoming webhooks created by those providers. Paste the incoming-webhook URL into Affonso; you do not need to connect a Slack or Discord account through OAuth.
Channel notifications contain a curated subset of useful event fields. Sensitive and unrelated fields from the complete event payload are not copied into the channel message.
What You Get Notified About
- Affiliate events: new signups, profile updates, status changes
- Referral events: new referrals, conversions
- Commission events: created, approved, rejected
- Payout events: initiated, completed, failed
- Coupon events: created, updated, and deleted
Setting Up Webhooks
- Go to Connect → Webhooks in your dashboard
- Click Add Endpoint
- Enter your endpoint or incoming-webhook URL
- Select Raw JSON, Slack, or Discord as the format
- Select the events you want to receive and save the endpoint
- Open the endpoint and click Send test event in Deliveries.
- Select one of the endpoint's subscribed events, review the mock payload, and click Send test event.
When you paste a recognized Slack or Discord incoming-webhook URL while creating an endpoint, Affonso suggests the matching format. You can always change the selection before saving.
For provider-specific instructions, see Set up Slack webhook notifications or Set up Discord webhook notifications.
Security
Every Raw JSON webhook payload is signed with HMAC-SHA256. Verify the X-Affonso-Signature against the exact request body and use X-Affonso-Timestamp to reject stale requests. Save the one-time endpoint secret when it is shown after creating or rotating a Raw JSON endpoint.
Slack and Discord authenticate incoming delivery through the credential in their webhook URL, so they do not use the Affonso HMAC headers. Treat incoming-webhook URLs as secrets and rotate them in Slack or Discord if they are exposed.
Failed deliveries are retried with exponential backoff. You can also redeliver completed events from the delivery log. Redelivery creates a new delivery while preserving the original attempt history. See Redeliver a webhook delivery for timing and duplicate-processing guidance.
Test an event-specific integration
Send test event uses the selected production event type and payload shape with synthetic data. It does not create or read an affiliate, referral, transaction, payout, coupon, or customer. The attempt appears in delivery history with a Test badge, including its HTTP status, latency, safe response excerpt, and error details.
Raw JSON test events include test: true in the payload and X-Affonso-Test: true in the request headers. They use the endpoint's normal X-Affonso-Timestamp and X-Affonso-Signature; verify the signature against the exact received body as you would in production. Your handler can use the test marker to route or ignore test activity.
Slack and Discord test notifications keep the selected event's title and fields and add a visible Test label. Failed test events are not retried, do not affect endpoint health, and cannot be redelivered. Send a new test event after fixing the destination.
Common Use Cases
- Slack or Discord notification when a new affiliate joins
- CRM update when a referral converts
- Custom email when a payout is processed
- Analytics tracking for every conversion
Full Documentation
For payload formats, signature verification, and event details:
