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

# Refairn Webhook Events: Inbound Integration Reference

> Reference for all Refairn inbound events—customer lifecycle, payment, and subscription signals that drive attribution and commission calculation.

Events are the language Refairn uses to stay in sync with your SaaS product. Every time a customer signs up, subscribes, upgrades, or cancels, your system (or your payment provider) fires an event that Refairn uses to update attribution records and trigger commission logic. Understanding how these events flow—and what data each one carries—is essential for a reliable integration.

## How events flow

There are two directions of event traffic in a Refairn integration:

* **Inbound events (you → Refairn):** Your SaaS backend or payment provider sends events to Refairn when customer and payment state changes. These drive referral attribution and commission calculation.
* **Outbound events (Refairn → you):** In a future release, Refairn will send webhook notifications to your system when commissions are approved, held, or disbursed. This direction is not yet available—see the note below.

<Info>
  Outbound webhooks from Refairn to your system (for example, `commission.approved` or `payout.released` notifications) are planned for a future release. This page documents the inbound events your integration should send to Refairn today.
</Info>

## Authentication

All inbound event requests must include your API key as a Bearer token in the `Authorization` header. API keys are generated per business in **Settings → Integrations** in your business dashboard.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

For payment provider webhooks (Stripe, Paystack, etc.), authentication is handled by Refairn verifying the provider's webhook signature automatically. You do not need to pass an API key for those—just configure the correct webhook URL for your business.

## Error handling and retries

Refairn returns standard HTTP status codes:

| Code  | Meaning                                           |
| ----- | ------------------------------------------------- |
| `200` | Event received and processed successfully         |
| `400` | Bad request — check your payload fields           |
| `401` | Unauthorized — check your API key                 |
| `409` | Conflict — duplicate event (use idempotency keys) |
| `5xx` | Server error — safe to retry                      |

For `5xx` errors, implement exponential backoff with at least three retry attempts. Events are idempotent: sending the same event twice with the same customer email and payment date will not generate duplicate commissions. However, if your system does not have natural idempotency, include a unique `eventId` field in your payload to let Refairn deduplicate explicitly.

***

## Inbound event types

These are the events your SaaS backend should send to Refairn as customers move through their lifecycle.

<Accordion title="customer.signed_up — Customer created an account">
  Fired when a new customer creates an account through a referral link. Send this event from your signup flow immediately after account creation succeeds. Refairn uses it to record the lead, link it to the referring agent, and start the attribution window.

  **Endpoint:** `POST /api/events/customer-created`

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "customerName": "Jane Smith",
    "referralCode": "AGENT123"
  }
  ```

  **Response:**

  ```json theme={null}
  {
    "success": true,
    "leadId": "lead_abc123",
    "agentId": "agent_xyz456",
    "attribution": "first_touch",
    "message": "Customer recorded and attributed to agent."
  }
  ```

  **Notes:**

  * `referralCode` is the agent's unique code, captured from the referral link click cookie. If the customer did not arrive via a referral link, omit this field.
  * Attribution is assigned at the `first_touch` point—the first referral link click recorded for this email address.
</Accordion>

<Accordion title="customer.subscribed — Customer started a paid subscription">
  Fired when a customer moves from a free or trial state to an active paid subscription. This event, combined with the corresponding `payment.succeeded` event, is what triggers the initial referral commission for the attributing agent.

  **Endpoint:** `POST /api/events/payment-succeeded`

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "amount": 99,
    "currency": "USD",
    "subscriptionStatus": "active",
    "paymentDate": "2026-06-14"
  }
  ```

  **Response:**

  ```json theme={null}
  {
    "success": true,
    "commissionId": "comm_abc123",
    "agentId": "agent_xyz456",
    "commissionAmount": 19.80,
    "commissionStatus": "pending",
    "holdUntil": "2026-06-28"
  }
  ```
</Accordion>

<Accordion title="customer.upgraded — Customer moved to a higher plan">
  Fired when a customer upgrades their subscription to a plan with a higher monthly or annual value. Refairn recalculates the recurring commission amount based on the new plan value. The delta in plan value may generate an incremental commission depending on your program's commission rules.

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "amount": 199,
    "currency": "USD",
    "subscriptionStatus": "active",
    "paymentDate": "2026-07-01",
    "previousAmount": 99,
    "eventType": "upgrade"
  }
  ```
</Accordion>

<Accordion title="customer.downgraded — Customer moved to a lower plan">
  Fired when a customer downgrades their subscription. Refairn adjusts future recurring commission calculations to reflect the new lower plan value. Commissions already approved for prior periods are not clawed back.

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "amount": 49,
    "currency": "USD",
    "subscriptionStatus": "active",
    "paymentDate": "2026-07-01",
    "previousAmount": 99,
    "eventType": "downgrade"
  }
  ```
</Accordion>

<Accordion title="customer.cancelled — Subscription cancelled">
  Fired when a customer cancels their subscription. Refairn stops generating future recurring commissions for this customer from the cancellation date. Commissions already approved for prior billing periods are unaffected.

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "subscriptionStatus": "cancelled",
    "cancellationDate": "2026-07-15"
  }
  ```

  **Notes:**

  * Send this event on the effective cancellation date, not on the end-of-access date if your product offers access until the end of a billing cycle.
  * If the cancellation is reversed before it takes effect, send a `customer.reactivated` event.
</Accordion>

<Accordion title="payment.succeeded — Payment confirmed">
  The primary event that triggers commission calculation. Fired every time a qualifying payment is confirmed—whether it is an initial subscription, a renewal, or a one-time charge. Refairn looks up the referring agent for the customer's email and queues the corresponding commission.

  **Endpoint:** `POST /api/events/payment-succeeded`

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "amount": 99,
    "currency": "USD",
    "subscriptionStatus": "active",
    "paymentDate": "2026-06-14"
  }
  ```

  **Response:**

  ```json theme={null}
  {
    "success": true,
    "commissionId": "comm_abc123",
    "agentId": "agent_xyz456",
    "commissionAmount": 19.80,
    "commissionStatus": "pending",
    "holdUntil": "2026-06-28"
  }
  ```

  **Notes:**

  * Commission is held for a configurable period (default: 14 days) before it moves to `approved` status, to allow for refund and dispute windows.
  * If no agent attribution exists for this customer email, Refairn records the payment but does not create a commission.
</Accordion>

<Accordion title="payment.failed — Payment attempt failed">
  Fired when a payment attempt is declined or fails. No commission is generated for failed payments. If your program tracks customer health signals for agent performance ratings, Refairn may record the failure as a risk event.

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "amount": 99,
    "currency": "USD",
    "subscriptionStatus": "past_due",
    "paymentDate": "2026-07-01",
    "failureReason": "card_declined"
  }
  ```
</Accordion>

<Accordion title="customer.reactivated — Cancelled customer returned">
  Fired when a previously cancelled customer reactivates their subscription. Refairn applies the original agent's attribution if the reactivation falls within your program's attribution window. If the window has expired, the reactivation is treated as a new customer event with no agent attribution.

  ```json theme={null}
  {
    "businessId": "business_123",
    "productId": "product_123",
    "customerEmail": "jane@example.com",
    "amount": 99,
    "currency": "USD",
    "subscriptionStatus": "active",
    "paymentDate": "2026-09-01",
    "eventType": "reactivation"
  }
  ```

  **Notes:**

  * The attribution window is configured per program in your commission settings.
  * If the same customer was referred by a different agent during the gap period, a conflict resolution rule applies. Contact support if you need to configure custom reactivation attribution logic.
</Accordion>