> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> All 13 webhook event types with payload examples.

AgentRef sends 13 event types grouped into 5 categories. Subscribe only to the events you need when creating a webhook endpoint.

<Info>
  Marketing Resources lifecycle changes do not currently emit webhook events.
</Info>

## Envelope Format

Every event is wrapped in the same envelope:

```json theme={null}
{
  "id": "msg_abc123",
  "type": "conversion.created",
  "schemaVersion": 2,
  "createdAt": "2026-03-23T14:30:00.000Z",
  "merchantId": "mer_abc123",
  "programId": "prg_xyz789",
  "environment": "production",
  "data": {}
}
```

| Field           | Type      | Description                               |
| --------------- | --------- | ----------------------------------------- |
| `id`            | `string`  | Unique message ID (use for idempotency)   |
| `type`          | `string`  | Event type (see below)                    |
| `schemaVersion` | `2`       | Always `2`                                |
| `createdAt`     | `string`  | ISO 8601 timestamp                        |
| `merchantId`    | `string`  | Your merchant ID                          |
| `programId`     | `string?` | Program ID (if event is program-scoped)   |
| `environment`   | `string`  | `production`, `preview`, or `development` |
| `data`          | `object`  | Event-specific payload                    |

***

## Program Events

<Accordion title="program.created">
  Fired when a new affiliate program is created.

  ```json theme={null}
  {
    "id": "msg_001",
    "type": "program.created",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T14:30:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "prg_xyz789",
      "name": "Pro Plan Affiliates",
      "commissionType": "recurring",
      "commissionPercent": 30,
      "cookieDuration": 90,
      "status": "active"
    }
  }
  ```
</Accordion>

<Accordion title="program.updated">
  Fired when program settings are changed (name, commission, cookie duration, etc.).

  ```json theme={null}
  {
    "id": "msg_002",
    "type": "program.updated",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T14:31:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "prg_xyz789",
      "name": "Pro Plan Affiliates",
      "commissionType": "recurring",
      "commissionPercent": 35,
      "cookieDuration": 90,
      "status": "active",
      "updatedFields": ["commissionPercent"]
    }
  }
  ```
</Accordion>

## Affiliate Events

<Accordion title="affiliate.joined">
  Fired when an affiliate joins your program (via invite link or marketplace).

  ```json theme={null}
  {
    "id": "msg_003",
    "type": "affiliate.joined",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T15:00:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "aff_def456",
      "programId": "prg_xyz789",
      "email": "affiliate@example.com",
      "name": "Jane Smith",
      "code": "jane",
      "joinSource": "invite",
      "isApproved": false,
      "isBlocked": false,
      "joinedAt": "2026-03-23T15:00:00.000Z",
      "approvedAt": null,
      "blockedAt": null
    }
  }
  ```
</Accordion>

<Accordion title="affiliate.approved">
  Fired when a pending affiliate is approved.

  ```json theme={null}
  {
    "id": "msg_004",
    "type": "affiliate.approved",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T15:05:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "aff_def456",
      "programId": "prg_xyz789",
      "email": "affiliate@example.com",
      "name": "Jane Smith",
      "code": "jane",
      "isApproved": true,
      "isBlocked": false,
      "approvedAt": "2026-03-23T15:05:00.000Z"
    }
  }
  ```
</Accordion>

<Accordion title="affiliate.blocked">
  Fired when an affiliate is blocked (manually or by fraud detection).

  ```json theme={null}
  {
    "id": "msg_005",
    "type": "affiliate.blocked",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T16:00:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "aff_def456",
      "programId": "prg_xyz789",
      "email": "affiliate@example.com",
      "isApproved": true,
      "isBlocked": true,
      "blockedReason": "Suspicious click patterns detected",
      "blockedAt": "2026-03-23T16:00:00.000Z"
    }
  }
  ```
</Accordion>

<Accordion title="affiliate.unblocked">
  Fired when a previously blocked affiliate is reinstated.

  ```json theme={null}
  {
    "id": "msg_006",
    "type": "affiliate.unblocked",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T17:00:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "aff_def456",
      "programId": "prg_xyz789",
      "email": "affiliate@example.com",
      "isApproved": true,
      "isBlocked": false,
      "blockedReason": null,
      "blockedAt": null,
      "updatedAt": "2026-03-23T17:00:00.000Z"
    }
  }
  ```
</Accordion>

## Conversion Events

<Accordion title="conversion.created">
  Fired when a new conversion is recorded from a supported attribution source such as Stripe metadata, Stripe `client_reference_id`, or coupon attribution.

  ```json theme={null}
  {
    "id": "msg_007",
    "type": "conversion.created",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T18:00:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "conv_ghi789",
      "affiliateId": "aff_def456",
      "programId": "prg_xyz789",
      "clickId": "clk_abc123",
      "paymentProvider": "stripe",
      "externalId": "cs_live_abc123",
      "saleAmount": 9900,
      "refundedAmount": 0,
      "currency": "usd",
      "isRecurring": false,
      "recurringMonth": null,
      "status": "pending",
      "attributionMethod": "click_token",
      "createdAt": "2026-03-23T18:00:00.000Z"
    }
  }
  ```
</Accordion>

<Accordion title="conversion.refunded">
  Fired when a conversion is refunded (triggered by Stripe refund or manual action).

  ```json theme={null}
  {
    "id": "msg_008",
    "type": "conversion.refunded",
    "schemaVersion": 2,
    "createdAt": "2026-03-23T19:00:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "conv_ghi789",
      "affiliateId": "aff_def456",
      "programId": "prg_xyz789",
      "paymentProvider": "stripe",
      "externalId": "ch_abc123",
      "saleAmount": 9900,
      "refundedAmount": 9900,
      "currency": "usd",
      "status": "refunded",
      "updatedAt": "2026-03-23T19:00:00.000Z"
    }
  }
  ```
</Accordion>

## Payout Events

<Accordion title="payout.created">
  Fired when a payout is created for an affiliate.

  ```json theme={null}
  {
    "id": "msg_009",
    "type": "payout.created",
    "schemaVersion": 2,
    "createdAt": "2026-03-24T10:00:00.000Z",
    "merchantId": "mer_abc123",
    "environment": "production",
    "data": {
      "id": "pay_jkl012",
      "affiliateId": "aff_def456",
      "programId": "prg_xyz789",
      "amount": 15000,
      "feeAmount": 0,
      "netAmount": 15000,
      "currency": "usd",
      "method": "paypal",
      "status": "pending",
      "periodStart": "2026-03-01T00:00:00.000Z",
      "periodEnd": "2026-03-31T23:59:59.000Z",
      "createdAt": "2026-03-24T10:00:00.000Z"
    }
  }
  ```
</Accordion>

<Accordion title="payout.processing">
  Fired when a payout moves into the manual processing step after the merchant starts the external payment.

  ```json theme={null}
  {
    "id": "msg_010",
    "type": "payout.processing",
    "schemaVersion": 2,
    "createdAt": "2026-03-24T10:05:00.000Z",
    "merchantId": "mer_abc123",
    "environment": "production",
    "data": {
      "id": "pay_jkl012",
      "affiliateId": "aff_def456",
      "programId": "prg_xyz789",
      "amount": 15000,
      "netAmount": 15000,
      "currency": "usd",
      "method": "paypal",
      "status": "processing"
    }
  }
  ```
</Accordion>

<Accordion title="payout.completed">
  Fired when a payout is marked completed after the external payment succeeds.

  ```json theme={null}
  {
    "id": "msg_011",
    "type": "payout.completed",
    "schemaVersion": 2,
    "createdAt": "2026-03-24T12:00:00.000Z",
    "merchantId": "mer_abc123",
    "environment": "production",
    "data": {
      "id": "pay_jkl012",
      "affiliateId": "aff_def456",
      "programId": "prg_xyz789",
      "amount": 15000,
      "netAmount": 15000,
      "currency": "usd",
      "method": "paypal",
      "status": "completed",
      "processedAt": "2026-03-24T10:05:00.000Z",
      "completedAt": "2026-03-24T12:00:00.000Z"
    }
  }
  ```
</Accordion>

<Accordion title="payout.failed">
  Fired when a manual payout attempt fails and the payout is marked for retry or follow-up.

  ```json theme={null}
  {
    "id": "msg_012",
    "type": "payout.failed",
    "schemaVersion": 2,
    "createdAt": "2026-03-24T12:00:00.000Z",
    "merchantId": "mer_abc123",
    "environment": "production",
    "data": {
      "id": "pay_jkl012",
      "affiliateId": "aff_def456",
      "programId": "prg_xyz789",
      "amount": 15000,
      "netAmount": 15000,
      "currency": "usd",
      "method": "paypal",
      "status": "failed",
      "failureReason": "External payment rejected by provider"
    }
  }
  ```
</Accordion>

## Fraud Events

<Accordion title="flag.resolved">
  Fired when a fraud flag is resolved (approved or rejected).

  ```json theme={null}
  {
    "id": "msg_013",
    "type": "flag.resolved",
    "schemaVersion": 2,
    "createdAt": "2026-03-24T14:00:00.000Z",
    "merchantId": "mer_abc123",
    "programId": "prg_xyz789",
    "environment": "production",
    "data": {
      "id": "flag_mno345",
      "affiliateId": "aff_def456",
      "type": "suspicious_click_pattern",
      "resolution": "dismissed",
      "resolvedAt": "2026-03-24T14:00:00.000Z",
      "resolvedBy": "merchant"
    }
  }
  ```
</Accordion>

## Quick Reference

| Event                 | Category   | When                      |
| --------------------- | ---------- | ------------------------- |
| `program.created`     | Program    | New program created       |
| `program.updated`     | Program    | Program settings changed  |
| `affiliate.joined`    | Affiliate  | Affiliate joins program   |
| `affiliate.approved`  | Affiliate  | Affiliate approved        |
| `affiliate.blocked`   | Affiliate  | Affiliate blocked         |
| `affiliate.unblocked` | Affiliate  | Affiliate reinstated      |
| `conversion.created`  | Conversion | New conversion recorded   |
| `conversion.refunded` | Conversion | Conversion refunded       |
| `payout.created`      | Payout     | Payout created            |
| `payout.processing`   | Payout     | Payout processing started |
| `payout.completed`    | Payout     | Payout marked completed   |
| `payout.failed`       | Payout     | Payout failed             |
| `flag.resolved`       | Fraud      | Fraud flag resolved       |