What affiliate software webhooks actually do
Affiliate software with webhook integrations can notify your application when a promoter joins, a referral converts or a commission changes. Webhooks are useful for CRM updates, in-app rewards, accounting and partner lifecycle automation. But a webhook from your billing provider is not the same as a webhook from your affiliate platform. A reliable SaaS setup usually needs both, with clear ownership of the commission ledger.
Do not choose a tool solely because its website says “webhooks supported.” Verify which events are available, which plans include them, how requests are authenticated and what happens when your server is unavailable.
Which events matter for a SaaS program?
| Event family | Business action | What to verify |
|---|---|---|
| Affiliate created or approved | Provision partner access | Partner ID, campaign, approval state |
| Referral lead or conversion | Connect signup to campaign | Referral ID, customer reference, attribution window |
| Commission created or approved | Update payable ledger | Commission ID, currency, eligible amount |
| Commission reversed | Adjust accrual | Refund, dispute, duplicate handling |
| Payout due or completed | Reconcile payment status | Who actually transfers money |
Event names and payload schemas vary. Do not assume that a generic conversion event represents a settled payment or that a payout notification authorizes a bank transfer.
Vendor documentation: FirstPromoter and Rewardful
FirstPromoter documents webhook configuration under Settings → Integrations → Webhooks, event selection by campaign, delivery history, a test button and retry behavior. Its public guide describes three default retries after a failed delivery. Validate the exact event and retry contract for your account and version.
Rewardful documents outbound webhook endpoints over HTTPS, selectable event types and an event log with resend options. Its developer documentation separates object, event and request data in the payload. This is enough to design a basic receiver, but verify signature handling and event IDs using its current developer docs before deploying.
Neither vendor's affiliate events should be mistaken for Stripe or Paddle's financial source of truth. For a refund, confirm both the billing event and the resulting commission adjustment.
Webhook signature verification and secure delivery
- Use a dedicated HTTPS endpoint and store any signing secret in server configuration, never in client-side code.
- Verify the provider's documented signature or authenticated header against the raw request body where required. Reject invalid requests before business processing.
- Record a provider event ID, event type and delivery time; enforce an idempotency key so duplicate deliveries cannot create duplicate credits or commissions.
- Acknowledge quickly after safely persisting the event to a queue. Process slow downstream work asynchronously and retry transient failures.
- Reconcile out-of-order notifications against the current API record before making irreversible changes.
Paddle's official SDK verification uses the Paddle-Signature header, the raw payload and the endpoint secret. That signing procedure applies to Paddle events, not automatically to FirstPromoter or Rewardful events.
A subscription-ready webhook architecture
Suggested flow: referral click → consent-aware identifier → authenticated account → billing customer/subscription → verified payment event → affiliate conversion → commission entry → approval and payout. Store mapping IDs in your own ledger and record each transition, rather than overwriting the previous state.
For Stripe Billing, compare affiliate commissions with collected invoice payments and later credit notes or refunds. For Paddle Billing, distinguish transaction.paid, subscription.created and transaction.completed; the vendor documents their different purposes. Paddle also recommends responding with HTTP 200 within five seconds. See Paddle Billing affiliate integrations.
If the affiliate platform supports both an API and webhooks, use the API for periodic backfills. Our affiliate API guide covers pagination, permissions and reconciliation.
Failure scenarios you should simulate
- Repeated delivery: same event arrives twice; one ledger entry must remain.
- Out-of-order events: a refund arrives before the original conversion; reconcile by immutable payment ID.
- Endpoint downtime: check the vendor's retry window and manual redelivery procedure.
- Unauthorized request: an invalid signature or token must be rejected.
- Subscription renewal: an eligible second invoice produces exactly one additional commission.
- Partial refund: verify whether the commission adjustment follows your program policy.
- Plan change: upgrade or downgrade must not be counted as a new customer unless terms say so.
Keep a small test ledger with columns for billing event ID, affiliate ID, expected commission, actual commission, adjustment and outcome. This is more informative than simply observing a successful HTTP response.
Vendor selection checklist
Ask for the complete event catalog, signature verification instructions, rate limits, webhook delivery log, test-event tool, retry policy, support for separate test and live environments, and an example payload. Confirm whether payouts, refunds and recurring invoices generate events. Check pricing-plan restrictions and data retention. A platform with fewer documented events may still work if its API supports reliable reconciliation, but estimate the additional engineering effort.
For privacy and cross-device limits, read cookie versus server-side tracking and recurring commission tracking.
Official sources and editorial disclosure
Documentation checked 24 October 2026. No paid hands-on testing, synthetic reviews or unverified payout guarantees are claimed. See our research methodology and affiliate disclosure.