Webhook Events

Icodrip can send real-time webhook notifications to your server when important events occur. Webhooks let you react to conversions, payouts, and affiliate activity in your own application without polling the API.

Common use cases include: updating your CRM when a new affiliate signs up, triggering an internal workflow when a conversion is recorded, sending a Slack notification when a payout is processed, or syncing affiliate data with your data warehouse.

Webhooks are delivered as HTTP POST requests to a URL you specify. Each request includes a JSON payload with the event type and relevant data. Icodrip signs every webhook so you can verify it came from us and was not tampered with.

Icodrip sends webhooks for the following event types. Affiliate events: affiliate.created, affiliate.updated, affiliate.approved, affiliate.suspended. Conversion events: conversion.created, conversion.updated, conversion.refunded. Payout events: payout.created, payout.completed, payout.failed.

You can subscribe to specific event types when configuring your webhook endpoint. Only the events you select will be delivered. This prevents your endpoint from being overwhelmed with events you do not need.

Each event type includes a comprehensive payload with all relevant data. For example, conversion.created includes the conversion amount, commission calculated, attributed affiliate, and the original click data. You do not need to make additional API calls to get the full picture.

Webhook payloads follow a consistent JSON structure. The top-level object includes: id (a unique event ID), type (the event type string), created_at (UTC timestamp), and data (an object with the event-specific payload).

The data object contains the full resource that triggered the event. For a conversion.created event, the data object is the complete conversion record including amount, commission, affiliate details, and attribution metadata. For payout.completed, it includes the payout amount, recipient affiliate, and Stripe transfer ID.

All monetary values in webhook payloads are in cents (integer) to avoid floating-point precision issues. Timestamps are in ISO 8601 format with UTC timezone. IDs use the standard Icodrip prefixed format (conv_, pay_, aff_, etc.).

Every webhook request includes an X-Icodrip-Signature header containing an HMAC-SHA256 signature. You should verify this signature before processing any webhook to ensure the request came from Icodrip and was not modified in transit.

To verify, compute the HMAC-SHA256 hash of the raw request body using your webhook signing secret as the key. Compare the computed hash with the value in the X-Icodrip-Signature header. If they match, the webhook is authentic.

Your webhook signing secret is generated when you create the webhook endpoint. It is displayed once — copy and store it securely. If you lose the secret, you can regenerate it in the webhook settings, but this invalidates the old secret immediately.

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, Icodrip retries the delivery. The retry schedule uses exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, and 24 hours. After 5 failed attempts, the webhook is marked as failed and no further retries are attempted.

You can view the delivery history for each webhook endpoint in your dashboard. Each delivery attempt shows the response status code, response body (truncated), and timestamp. This helps you debug issues with your endpoint.

To handle retries safely, make your webhook handler idempotent. Use the event ID (included in every payload) to detect duplicate deliveries. If you have already processed an event with a given ID, return a 200 status without reprocessing. This prevents duplicate side effects like sending multiple notifications for the same conversion.