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

​
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": { ... }
}
FieldTypeDescription
idstringUnique message ID (use for idempotency)
typestringEvent type (see below)
schemaVersion2Always 2
createdAtstringISO 8601 timestamp
merchantIdstringYour merchant ID
programIdstring?Program ID (if event is program-scoped)
environmentstringproduction, preview, or development
dataobjectEvent-specific payload

​
Program Events

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": "percentage",
    "commissionValue": 30,
    "cookieDuration": 90,
    "status": "active"
  }
}
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": "percentage",
    "commissionValue": 35,
    "cookieDuration": 90,
    "status": "active",
    "updatedFields": ["commissionValue"]
  }
}

​
Affiliate Events

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",
    "email": "affiliate@example.com",
    "name": "Jane Smith",
    "referralCode": "jane",
    "status": "pending",
    "joinedAt": "2026-03-23T15:00:00.000Z"
  }
}
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",
    "email": "affiliate@example.com",
    "name": "Jane Smith",
    "referralCode": "jane",
    "status": "active",
    "approvedAt": "2026-03-23T15:05:00.000Z"
  }
}
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",
    "email": "affiliate@example.com",
    "status": "blocked",
    "reason": "Suspicious click patterns detected",
    "blockedAt": "2026-03-23T16:00:00.000Z"
  }
}
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",
    "email": "affiliate@example.com",
    "status": "active",
    "unblockedAt": "2026-03-23T17:00:00.000Z"
  }
}

​
Conversion Events

Fired when a new conversion is recorded (from Stripe or manually via API).
{
  "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",
    "amount": 9900,
    "currency": "usd",
    "commissionAmount": 2970,
    "status": "pending",
    "externalId": "cs_live_abc123",
    "createdAt": "2026-03-23T18:00:00.000Z"
  }
}
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",
    "amount": 9900,
    "currency": "usd",
    "commissionAmount": 2970,
    "status": "refunded",
    "refundedAt": "2026-03-23T19:00:00.000Z"
  }
}

​
Payout Events

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",
    "amount": 15000,
    "currency": "usd",
    "status": "pending",
    "createdAt": "2026-03-24T10:00:00.000Z"
  }
}
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",
    "amount": 15000,
    "currency": "usd",
    "status": "processing"
  }
}
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",
    "amount": 15000,
    "currency": "usd",
    "status": "completed",
    "completedAt": "2026-03-24T12:00:00.000Z"
  }
}
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",
    "amount": 15000,
    "currency": "usd",
    "status": "failed",
    "failureReason": "External payment rejected by provider",
    "failedAt": "2026-03-24T12:00:00.000Z"
  }
}

​
Fraud Events

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

EventCategoryWhen
program.createdProgramNew program created
program.updatedProgramProgram settings changed
affiliate.joinedAffiliateAffiliate joins program
affiliate.approvedAffiliateAffiliate approved
affiliate.blockedAffiliateAffiliate blocked
affiliate.unblockedAffiliateAffiliate reinstated
conversion.createdConversionNew conversion recorded
conversion.refundedConversionConversion refunded
payout.createdPayoutPayout created
payout.processingPayoutPayout processing started
payout.completedPayoutPayout marked completed
payout.failedPayoutPayout failed
flag.resolvedFraudFraud flag resolved