Consume affiliate webhooks

What you need

A permitted public HTTPS endpoint you control and app integration permissions. Validation sends a real connection test to the entered endpoint.

Steps

1. Open Affiliate Developers and choose the intended app, destination kind and event types. Use a public HTTPS webhook or a Slack incoming webhook for Slack kind.
2. Prepare the signing secret where prompted and keep it private. Configure your receiver, then validate the exact current destination/event configuration.
3. The connection test must return 2xx. Save the validated configuration before the validation receipt expires. An edited URL/event selection needs fresh validation.
4. For webhook kind, verify X-HeyCrust-Timestamp and X-HeyCrust-Signature over the raw body before parsing or acting. Compute v1= plus hex HMAC-SHA256 of <timestamp>.<raw body> using the signing secret. Accept a ten-digit epoch timestamp within five minutes; compare signatures safely.
5. Deduplicate event IDs, persist processing state and return 2xx only when your receiver accepts the event. Review attempts/errors in the delivery controls; request a retry for a corrected dead/retry delivery when appropriate.
6. Revalidate updates using the current signing secret; when replacing/revoking a destination, update your receiver and revoke the obsolete subscription deliberately.

Expected result

A validated active destination and observable delivery attempts. A saved destination is not a guarantee that every later request reaches or is processed by your receiver.

Event envelope and catalog

The connection test has id, schemaVersion: 1, type: "connection.test", ISO occurredAt and data. Real deliveries follow the versioned envelope; use the event type and identifiers to load the current authorized record when needed rather than guessing a richer payload.

Event subscriptions include join request/join, referral/request, payment request, membership and terms changes, referral dispute/reassignment, commission updates/payable/bonus/refund, payout review, payment report/confirmation/dispute/resolution/reminders, tracking health and listing moderation. The exact event names below are generated from the current contract.

See Delivery troubleshooting.

Troubleshooting

Redirect responses are terminal. Most 4xx failures are terminal except 408/425/429; network/server/transient errors retry, up to eight attempts. Delay grows from one minute with a one-day cap. Fix the endpoint/signature/error before requesting manual retry. Slack URL/signing behavior differs from ordinary webhooks.

Supported event names

• join-request
• join
• referral
• referral-request
• payment-request
• membership.provisioned
• membership.rejected
• membership.suspended
• membership.archived
• membership.terms_updated
• membership.terms_proposed
• membership.terms_accepted
• program.terms_changed
• program.eligibility_changed
• referral.reject
• referral.dispute
• referral.reassigned
• commission.updated
• commission.payable
• commission.bonus
• commission.refunded
• payout.approved
• payout.rejected
• payment.reported
• payment.confirmed
• payment.disputed
• payment.resolved
• payment.reminder
• payment.confirmation_reminder
• tracking.health_changed
• listing.submitted
• listing.moderated