# Consume affiliate webhooks

Validate the destination and verify signed event bodies before processing them.

## 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](/docs/help/troubleshooting#delivery).

## 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`