Webhook Events

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

Marketing Resources lifecycle changes do not currently emit webhook events.

Envelope Format

Every event is wrapped in the same envelope:

{
  "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

program.created

Fired when a new affiliate program is created.

{
  "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"
  }
}

program.updated

Fired when program settings are changed (name, commission, cookie duration, etc.).

{
  "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"]
  }
}

Affiliate Events

affiliate.joined

Fired when an affiliate joins your program (via invite link or marketplace).

{
  "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
  }
}

affiliate.approved

Fired when a pending affiliate is approved.

{
  "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"
  }
}

affiliate.blocked

Fired when an affiliate is blocked (manually or by fraud detection).

{
  "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"
  }
}

affiliate.unblocked

Fired when a previously blocked affiliate is reinstated.

{
  "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"
  }
}

Conversion Events

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.

{
  "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"
  }
}

conversion.refunded

Fired when a conversion is refunded (triggered by Stripe refund or manual action).

{
  "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"
  }
}

Payout Events

payout.created

Fired when a payout is created for an affiliate.

{
  "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"
  }
}

payout.processing

Fired when a payout moves into the manual processing step after the merchant starts the external payment.

{
  "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"
  }
}

payout.completed

Fired when a payout is marked completed after the external payment succeeds.

{
  "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"
  }
}

payout.failed

Fired when a manual payout attempt fails and the payout is marked for retry or follow-up.

{
  "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"
  }
}

Fraud Events

flag.resolved

Fired when a fraud flag is resolved (approved or rejected).

{
  "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"
  }
}

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

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Envelope Format

Program Events

Affiliate Events

Conversion Events

Payout Events

Fraud Events

Quick Reference

​Envelope Format

​Program Events

​Affiliate Events

​Conversion Events

​Payout Events

​Fraud Events

​Quick Reference

Envelope Format

Program Events

Affiliate Events

Conversion Events

Payout Events

Fraud Events

Quick Reference