Webhook Notifications

Receive real-time notifications when affiliates are created or deactivated in your programme, and when an in-app referral is counted. Webhooks let you sync affiliate state with your own systems automatically, with no polling required.

How It Works

When an affiliate is created or removed from your company, or an in-app referral is counted, Insert Affiliate sends an HTTP POST request to your configured webhook URL with details about the event. This happens automatically in the background and does not delay the affiliate operation.

Setting Up Webhooks

Go to Settings → Integrations tab
1. Scroll to the Webhook Notifications section
Enter your Webhook URL — this must use HTTPS
Optionally enter a Bearer Token — this will be sent in the Authorization header so your server can verify requests are genuinely from Insert Affiliate
Click Save Changes

Webhook Notifications section in the Insert Affiliate dashboard settings

Click to view full size

Your bearer token is encrypted at rest and never displayed in full after saving.

Webhook Events

`affiliate.created`

Sent when an affiliate is added to your company. This includes all creation methods: manually adding an affiliate from the dashboard, approving a self-signup application, or accepting an affiliate's join request.

Payload:

{
  "event": "affiliate.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "occurred_at": "2026-03-18T12:00:00.000Z"
}

Fields:

Field	Type	Description
`event`	string	Always `"affiliate.created"`
`affiliate_id`	string	A deterministic identifier for the affiliate, derived from their email. Format: `ia_` followed by 8 hexadecimal characters. Consistent across all events for the same affiliate.
`email`	string	The affiliate's email address
`deep_link`	string	The affiliate's assigned deep link URL. This is included when a deep link has been assigned (e.g. during self-signup approval or join request acceptance). May be an empty string if no deep link has been assigned yet.
`occurred_at`	string	ISO 8601 timestamp of when the event occurred

`affiliate.deactivated`

Sent when an affiliate is removed from your company.

Payload:

{
  "event": "affiliate.deactivated",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "occurred_at": "2026-03-18T14:30:00.000Z"
}

Fields:

Field	Type	Description
`event`	string	Always `"affiliate.deactivated"`
`affiliate_id`	string	The same deterministic identifier that was sent in the `affiliate.created` event for this affiliate. Use this to match creation and deactivation events.
`email`	string	The affiliate's email address
`deep_link`	string	The deep link URL that was assigned to the affiliate at the time of removal. Empty string if no deep link was assigned.
`occurred_at`	string	ISO 8601 timestamp of when the event occurred

`referral.created`

Sent when something your in-app referral program counts as a referral happens: a new purchase, the event you chose, or an install, depending on your setting. Only sent when in-app referrals are turned on, for referrers who joined from your app.

Payload:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Fields:

Field	Type	Description
`event`	string	Always `"referral.created"`
`affiliate_id`	string	The same identifier sent in `affiliate.created` for this affiliate
`email`	string	The referrer's email address
`deep_link`	string	The referrer's link, or their short code for Short Code Only companies
`short_code`	string	The referrer's short code
`trigger`	string	What was counted: `"purchase"`, `"event"` or `"install"`
`referral_count`	number	The referrer's new running total. Reward up to this number, so you never reward twice and the next delivery catches up any you missed.
`reward_status`	string	What happened to the automatic reward when the referral was recorded: `granted`, `not_automatic` (no automatic reward: reward them yourself if you chose I'll reward them myself), `waiting_for_account`, `waiting_for_codes` (waiting for Apple to make offer codes, or for you to upload more Google Play promo codes; we retry every hour), `failed` or `capped` (over the monthly limit, don't reward this one). Sent once: a waiting reward given later sends no second webhook. See the full list.
`occurred_at`	string	ISO 8601 timestamp of when the event occurred

Authentication

If you configured a bearer token, every webhook request includes the header:

Authorization: Bearer

Your server should verify this header matches the token you configured in Insert Affiliate to ensure requests are legitimate.

Behaviour Notes

Fire-and-forget — Webhook delivery does not block the affiliate operation. If your endpoint is down or returns an error, the affiliate is still created or removed as normal.
HTTPS only — Webhook URLs must use HTTPS for security.
Timeout — Requests time out after 10 seconds. Ensure your endpoint responds promptly.
No retries — Failed webhooks are not retried. If reliability is critical, consider logging received events on your end and periodically reconciling against the Insert Affiliate dashboard.
Consistent affiliate IDs — The affiliate_id is deterministic and based on the affiliate's email. The same email will always produce the same affiliate_id, so you can reliably match created and deactivated events.

Example Use Cases

Sync affiliates to your CRM — Automatically create or archive contacts when affiliates join or leave
Trigger onboarding workflows — Start an internal onboarding flow when a new affiliate is approved
Update your own database — Keep your user records in sync with affiliate status changes
Slack or email alerts — Forward events to a notification channel for your team