Webhook Notifications

Receive real-time notifications when affiliates are created or deactivated in your programme. Webhooks let you sync affiliate state with your own systems automatically — no polling required.

How It Works

When an affiliate is created or removed from your company, 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
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

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": "affiliate@example.com",
  "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": "affiliate@example.com",
  "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

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