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.
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.
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 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 developmentdataobjectEvent-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" : "recurring" , "commissionPercent" : 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" : "recurring" , "commissionPercent" : 35 , "cookieDuration" : 90 , "status" : "active" , "updatedFields" : [ "commissionPercent" ] } }
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" , "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 } }
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" } }
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" } }
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
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" } }
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
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" } }
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" } }
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" } }
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
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.createdProgram New program created program.updatedProgram Program settings changed affiliate.joinedAffiliate Affiliate joins program affiliate.approvedAffiliate Affiliate approved affiliate.blockedAffiliate Affiliate blocked affiliate.unblockedAffiliate Affiliate reinstated conversion.createdConversion New conversion recorded conversion.refundedConversion Conversion refunded payout.createdPayout Payout created payout.processingPayout Payout processing started payout.completedPayout Payout marked completed payout.failedPayout Payout failed flag.resolvedFraud Fraud flag resolved
