Webhook Event Types

This page is generated from the platform event registry. To regenerate, run pnpm --filter @fluveo/merchant-api ts:scripts/generate-webhook-events-doc.ts. Editing the file by hand will be reverted by the next regeneration.

Webhooks notify your application when events happen in your account. When an event occurs, we send an HTTP POST request to each configured endpoint with a JSON payload describing the event.

Payload Structure

Every webhook event follows this structure:

{
  "id": "evt_1abc2def3ghi",
  "object": "event",
  "type": "payment_intent.succeeded",
  "created": 1709942400,
  "livemode": false,
  "data": {
    "object": {}
  }
}

Verifying Webhook Signatures

Every webhook delivery includes a Fluveo-Signature header (Stripe-style) so you can verify the payload originated from our servers and was not tampered with. The legacy header X-Signature carries the same value and is still emitted for backwards compatibility. The header format is:

Fluveo-Signature: t=<timestamp>,v1=<signature>

The signature is computed as:

HMAC-SHA256(webhook_secret, "v1=" + timestamp + "." + payload)

Where:

webhook_secret is the signing secret returned at endpoint creation.
timestamp is the Unix timestamp from the t= portion of the header.
payload is the raw JSON request body.

Each delivery also includes a Webhook-Id header with the event id, letting you deduplicate without parsing the body.

Verification Example

# Manually verify a webhook signature:
TIMESTAMP="1709913600"
PAYLOAD='{"id":"evt_123","type":"payment_intent.succeeded"}'
SECRET="whsec_your_secret"

SIGNED="v1=${TIMESTAMP}.${PAYLOAD}"
echo -n "$SIGNED" | openssl dgst -sha256 -hmac "$SECRET"

Always verify webhook signatures before processing the event. Reject any request where the signature does not match, and reject any request whose t timestamp is more than 5 minutes in the past (replay protection).

Payment Intent Events

`payment_intent.canceled`

Occurs when a PaymentIntent is canceled.

{
  "id": "evt_001_example",
  "object": "event",
  "type": "payment_intent.canceled",
  "created": 1709942400,
  "livemode": false,
  "data": {
    "object": {
      "id": "pi_test_1234567890",
      "object": "payment_intent",
      "amount": 5000,
      "currency": "usd",
      "status": "canceled",
      "cancellation_reason": "requested_by_customer",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payment_intent.created`

Occurs when a new PaymentIntent is created.

{
  "id": "evt_002_example",
  "object": "event",
  "type": "payment_intent.created",
  "created": 1709942460,
  "livemode": false,
  "data": {
    "object": {
      "id": "pi_test_1234567890",
      "object": "payment_intent",
      "amount": 5000,
      "currency": "usd",
      "status": "requires_payment_method",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payment_intent.payment_failed`

Occurs when a PaymentIntent payment attempt fails.

{
  "id": "evt_003_example",
  "object": "event",
  "type": "payment_intent.payment_failed",
  "created": 1709942520,
  "livemode": false,
  "data": {
    "object": {
      "id": "pi_test_1234567890",
      "object": "payment_intent",
      "amount": 5000,
      "currency": "usd",
      "status": "requires_payment_method",
      "last_payment_error": {
        "code": "card_declined",
        "message": "Your card was declined."
      },
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payment_intent.requires_action`

Occurs when a PaymentIntent requires additional authentication or action.

{
  "id": "evt_004_example",
  "object": "event",
  "type": "payment_intent.requires_action",
  "created": 1709942580,
  "livemode": false,
  "data": {
    "object": {
      "id": "pi_test_1234567890",
      "object": "payment_intent",
      "amount": 5000,
      "currency": "usd",
      "status": "requires_action",
      "next_action": {
        "type": "redirect_to_url"
      },
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payment_intent.succeeded`

Occurs when a PaymentIntent has been successfully paid.

{
  "id": "evt_005_example",
  "object": "event",
  "type": "payment_intent.succeeded",
  "created": 1709942640,
  "livemode": false,
  "data": {
    "object": {
      "id": "pi_test_1234567890",
      "object": "payment_intent",
      "amount": 5000,
      "currency": "usd",
      "status": "succeeded",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Charge Events

`charge.failed`

Occurs when a charge attempt fails.

{
  "id": "evt_006_example",
  "object": "event",
  "type": "charge.failed",
  "created": 1709942700,
  "livemode": false,
  "data": {
    "object": {
      "id": "ch_test_1234567890",
      "object": "charge",
      "amount": 5000,
      "currency": "usd",
      "status": "failed",
      "failure_code": "card_declined",
      "failure_message": "Your card was declined.",
      "payment_intent": "pi_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`charge.refunded`

Occurs when a charge is fully or partially refunded.

{
  "id": "evt_007_example",
  "object": "event",
  "type": "charge.refunded",
  "created": 1709942760,
  "livemode": false,
  "data": {
    "object": {
      "id": "ch_test_1234567890",
      "object": "charge",
      "amount": 5000,
      "amount_refunded": 5000,
      "currency": "usd",
      "status": "succeeded",
      "refunded": true,
      "payment_intent": "pi_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`charge.succeeded`

Occurs when a charge is successfully created.

{
  "id": "evt_008_example",
  "object": "event",
  "type": "charge.succeeded",
  "created": 1709942820,
  "livemode": false,
  "data": {
    "object": {
      "id": "ch_test_1234567890",
      "object": "charge",
      "amount": 5000,
      "currency": "usd",
      "status": "succeeded",
      "payment_intent": "pi_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Refund Events

`refund.created`

Occurs when a refund is created.

{
  "id": "evt_009_example",
  "object": "event",
  "type": "refund.created",
  "created": 1709942880,
  "livemode": false,
  "data": {
    "object": {
      "id": "ref_test_1234567890",
      "object": "refund",
      "amount": 2500,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "status": "pending",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`refund.failed`

Occurs when a refund attempt fails (e.g. the destination card has been closed).

{
  "id": "evt_010_example",
  "object": "event",
  "type": "refund.failed",
  "created": 1709942940,
  "livemode": false,
  "data": {
    "object": {
      "id": "ref_test_1234567890",
      "object": "refund",
      "amount": 2500,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "status": "failed",
      "failure_reason": "expired_or_canceled_card",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`refund.updated`

Occurs when a refund is updated.

{
  "id": "evt_011_example",
  "object": "event",
  "type": "refund.updated",
  "created": 1709943000,
  "livemode": false,
  "data": {
    "object": {
      "id": "ref_test_1234567890",
      "object": "refund",
      "amount": 2500,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "status": "succeeded",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Dispute Events

`charge.dispute.closed`

Stripe-parity alias for dispute.closed. Fires alongside the canonical event.

{
  "id": "evt_012_example",
  "object": "event",
  "type": "charge.dispute.closed",
  "created": 1709943060,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_test_1234567890",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "charge": "ch_test_1234567890",
      "reason": "fraudulent",
      "status": "won",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`charge.dispute.created`

Stripe-parity alias for dispute.created. Fires alongside the canonical event.

{
  "id": "evt_013_example",
  "object": "event",
  "type": "charge.dispute.created",
  "created": 1709943120,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_test_1234567890",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "charge": "ch_test_1234567890",
      "reason": "fraudulent",
      "status": "needs_response",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`charge.dispute.updated`

Stripe-parity alias for dispute.updated. Fires alongside the canonical event.

{
  "id": "evt_014_example",
  "object": "event",
  "type": "charge.dispute.updated",
  "created": 1709943180,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_test_1234567890",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "charge": "ch_test_1234567890",
      "reason": "fraudulent",
      "status": "under_review",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`dispute.closed`

Occurs when a dispute is closed (won, lost, or charge_refunded).

{
  "id": "evt_015_example",
  "object": "event",
  "type": "dispute.closed",
  "created": 1709943240,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_test_1234567890",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "charge": "ch_test_1234567890",
      "reason": "fraudulent",
      "status": "won",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`dispute.created`

Occurs when a dispute is created.

{
  "id": "evt_016_example",
  "object": "event",
  "type": "dispute.created",
  "created": 1709943300,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_test_1234567890",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "charge": "ch_test_1234567890",
      "reason": "fraudulent",
      "status": "needs_response",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`dispute.evidence.required`

Fired when a dispute evidence submission deadline is approaching (within 7 days).

{
  "id": "evt_017_example",
  "object": "event",
  "type": "dispute.evidence.required",
  "created": 1709943360,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_xxx",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "charge": "ch_xxx",
      "payment_intent": "pi_xxx",
      "status": "needs_response",
      "reason": "fraudulent",
      "evidence_details": {
        "due_by": 1711929600
      },
      "livemode": true,
      "created": 1711843200
    }
  }
}

`dispute.updated`

Occurs when a dispute is updated (e.g. status change).

{
  "id": "evt_018_example",
  "object": "event",
  "type": "dispute.updated",
  "created": 1709943420,
  "livemode": false,
  "data": {
    "object": {
      "id": "dis_test_1234567890",
      "object": "dispute",
      "amount": 5000,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "charge": "ch_test_1234567890",
      "reason": "fraudulent",
      "status": "under_review",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Customer Events

`customer.created`

Occurs when a new customer is created.

{
  "id": "evt_019_example",
  "object": "event",
  "type": "customer.created",
  "created": 1709943480,
  "livemode": false,
  "data": {
    "object": {
      "id": "cus_test_1234567890",
      "object": "customer",
      "email": "customer@example.com",
      "name": "Jane Doe",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.deleted`

Occurs when a customer is permanently deleted.

{
  "id": "evt_020_example",
  "object": "event",
  "type": "customer.deleted",
  "created": 1709943540,
  "livemode": false,
  "data": {
    "object": {
      "id": "cus_test_1234567890",
      "object": "customer",
      "deleted": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.updated`

Occurs when a customer is updated.

{
  "id": "evt_021_example",
  "object": "event",
  "type": "customer.updated",
  "created": 1709943600,
  "livemode": false,
  "data": {
    "object": {
      "id": "cus_test_1234567890",
      "object": "customer",
      "email": "updated@example.com",
      "name": "Jane Doe",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Setup Intent Events

`setup_intent.created`

Occurs when a new SetupIntent is created.

{
  "id": "evt_022_example",
  "object": "event",
  "type": "setup_intent.created",
  "created": 1709943660,
  "livemode": false,
  "data": {
    "object": {
      "id": "seti_test_1234567890",
      "object": "setup_intent",
      "status": "requires_payment_method",
      "customer": "cus_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`setup_intent.setup_failed`

Occurs when a SetupIntent setup attempt fails.

{
  "id": "evt_023_example",
  "object": "event",
  "type": "setup_intent.setup_failed",
  "created": 1709943720,
  "livemode": false,
  "data": {
    "object": {
      "id": "seti_test_1234567890",
      "object": "setup_intent",
      "status": "requires_payment_method",
      "last_setup_error": {
        "code": "card_declined",
        "message": "Your card was declined."
      },
      "customer": "cus_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`setup_intent.succeeded`

Occurs when a SetupIntent has been successfully confirmed and the payment method is set up.

{
  "id": "evt_024_example",
  "object": "event",
  "type": "setup_intent.succeeded",
  "created": 1709943780,
  "livemode": false,
  "data": {
    "object": {
      "id": "seti_test_1234567890",
      "object": "setup_intent",
      "status": "succeeded",
      "payment_method": "pm_test_1234567890",
      "customer": "cus_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Subscription Events

`customer.subscription.created`

Stripe-parity alias for subscription.created. Fires alongside the canonical event.

{
  "id": "evt_025_example",
  "object": "event",
  "type": "customer.subscription.created",
  "created": 1709943840,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "incomplete",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.subscription.deleted`

Stripe-parity alias for subscription.deleted. Fires alongside the canonical event.

{
  "id": "evt_026_example",
  "object": "event",
  "type": "customer.subscription.deleted",
  "created": 1709943900,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "canceled",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "canceled_at": 1700000000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.subscription.past_due`

Stripe-parity alias for subscription.past_due. Fires alongside the canonical event.

{
  "id": "evt_027_example",
  "object": "event",
  "type": "customer.subscription.past_due",
  "created": 1709943960,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "past_due",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.subscription.resumed`

Stripe-parity alias for subscription.resumed. Fires alongside the canonical event.

{
  "id": "evt_028_example",
  "object": "event",
  "type": "customer.subscription.resumed",
  "created": 1709944020,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "active",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.subscription.trial_will_end`

Stripe-parity alias for subscription.trial_will_end. Fires alongside the canonical event.

{
  "id": "evt_029_example",
  "object": "event",
  "type": "customer.subscription.trial_will_end",
  "created": 1709944080,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "trialing",
      "trial_end": 1700000000,
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`customer.subscription.updated`

Stripe-parity alias for subscription.updated. Fires alongside the canonical event.

{
  "id": "evt_030_example",
  "object": "event",
  "type": "customer.subscription.updated",
  "created": 1709944140,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "active",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`subscription.created`

Occurs when a new subscription is created.

{
  "id": "evt_031_example",
  "object": "event",
  "type": "subscription.created",
  "created": 1709944200,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "incomplete",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`subscription.deleted`

Occurs when a subscription is immediately canceled.

{
  "id": "evt_032_example",
  "object": "event",
  "type": "subscription.deleted",
  "created": 1709944260,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "canceled",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "canceled_at": 1700000000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`subscription.past_due`

Occurs when a subscription payment fails and the subscription becomes past due.

{
  "id": "evt_033_example",
  "object": "event",
  "type": "subscription.past_due",
  "created": 1709944320,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "past_due",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`subscription.resumed`

Occurs when a paused subscription is resumed.

{
  "id": "evt_034_example",
  "object": "event",
  "type": "subscription.resumed",
  "created": 1709944380,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "active",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`subscription.trial_will_end`

Occurs three days before a subscription trial period ends. Use this to notify the customer.

{
  "id": "evt_035_example",
  "object": "event",
  "type": "subscription.trial_will_end",
  "created": 1709944440,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "trialing",
      "trial_end": 1700000000,
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`subscription.updated`

Occurs when a subscription is updated (e.g. payment method, collection method, metadata).

{
  "id": "evt_036_example",
  "object": "event",
  "type": "subscription.updated",
  "created": 1709944500,
  "livemode": false,
  "data": {
    "object": {
      "id": "sub_test_1234567890",
      "object": "subscription",
      "status": "active",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Invoice Events

`invoice.created`

Occurs when a new invoice is created.

{
  "id": "evt_037_example",
  "object": "event",
  "type": "invoice.created",
  "created": 1709944560,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "draft",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`invoice.finalized`

Occurs when an invoice is finalized and ready for payment.

{
  "id": "evt_038_example",
  "object": "event",
  "type": "invoice.finalized",
  "created": 1709944620,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "open",
      "number": "INV-0001",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`invoice.marked_uncollectible`

Occurs when an invoice is marked as uncollectible.

{
  "id": "evt_039_example",
  "object": "event",
  "type": "invoice.marked_uncollectible",
  "created": 1709944680,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "uncollectible",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`invoice.paid`

Occurs when an invoice is successfully paid.

{
  "id": "evt_040_example",
  "object": "event",
  "type": "invoice.paid",
  "created": 1709944740,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "paid",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "amount_paid": 5000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`invoice.payment_failed`

Occurs when payment for an invoice fails.

{
  "id": "evt_041_example",
  "object": "event",
  "type": "invoice.payment_failed",
  "created": 1709944800,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "open",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "attempt_count": 1,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`invoice.upcoming`

Occurs a few days before a subscription invoice is due. Use this to add extra invoice items.

{
  "id": "evt_042_example",
  "object": "event",
  "type": "invoice.upcoming",
  "created": 1709944860,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "draft",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`invoice.voided`

Occurs when an invoice is voided.

{
  "id": "evt_043_example",
  "object": "event",
  "type": "invoice.voided",
  "created": 1709944920,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "invoice",
      "status": "void",
      "customer": "cus_test_1234567890",
      "currency": "usd",
      "total": 5000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Product Events

`product.created`

Occurs when a new product is created.

{
  "id": "evt_044_example",
  "object": "event",
  "type": "product.created",
  "created": 1709944980,
  "livemode": false,
  "data": {
    "object": {
      "id": "prod_test_1234567890",
      "object": "product",
      "name": "Premium Widget",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`product.deleted`

Occurs when a product is deleted.

{
  "id": "evt_045_example",
  "object": "event",
  "type": "product.deleted",
  "created": 1709945040,
  "livemode": false,
  "data": {
    "object": {
      "id": "prod_test_1234567890",
      "object": "product",
      "deleted": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`product.updated`

Occurs when a product is updated.

{
  "id": "evt_046_example",
  "object": "event",
  "type": "product.updated",
  "created": 1709945100,
  "livemode": false,
  "data": {
    "object": {
      "id": "prod_test_1234567890",
      "object": "product",
      "name": "Premium Widget v2",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Price Events

`price.created`

Occurs when a new price is created.

{
  "id": "evt_047_example",
  "object": "event",
  "type": "price.created",
  "created": 1709945160,
  "livemode": false,
  "data": {
    "object": {
      "id": "price_test_1234567890",
      "object": "price",
      "unit_amount": 2500,
      "currency": "usd",
      "product": "prod_test_1234567890",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`price.deleted`

Occurs when a price is deleted.

{
  "id": "evt_048_example",
  "object": "event",
  "type": "price.deleted",
  "created": 1709945220,
  "livemode": false,
  "data": {
    "object": {
      "id": "price_test_1234567890",
      "object": "price",
      "deleted": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`price.updated`

Occurs when a price is updated.

{
  "id": "evt_049_example",
  "object": "event",
  "type": "price.updated",
  "created": 1709945280,
  "livemode": false,
  "data": {
    "object": {
      "id": "price_test_1234567890",
      "object": "price",
      "unit_amount": 3000,
      "currency": "usd",
      "product": "prod_test_1234567890",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Checkout Session Events

`checkout.session.completed`

Occurs when a checkout session is completed and payment is confirmed.

{
  "id": "evt_050_example",
  "object": "event",
  "type": "checkout.session.completed",
  "created": 1709945340,
  "livemode": false,
  "data": {
    "object": {
      "id": "cs_test_1234567890",
      "object": "checkout_session",
      "payment_intent": "pi_test_1234567890",
      "payment_status": "paid",
      "status": "complete",
      "amount_total": 5000,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`checkout.session.expired`

Occurs when a checkout session expires before completion.

{
  "id": "evt_051_example",
  "object": "event",
  "type": "checkout.session.expired",
  "created": 1709945400,
  "livemode": false,
  "data": {
    "object": {
      "id": "cs_test_1234567890",
      "object": "checkout_session",
      "payment_status": "unpaid",
      "status": "expired",
      "amount_total": 5000,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Checkout Link Events

`checkout_link.created`

Occurs when a new checkout link is created.

{
  "id": "evt_052_example",
  "object": "event",
  "type": "checkout_link.created",
  "created": 1709945460,
  "livemode": false,
  "data": {
    "object": {
      "id": "clink_test_1234567890",
      "object": "checkout_link",
      "url": "https://pay.example.com/c/clink_test_1234567890",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`checkout_link.updated`

Occurs when a checkout link is updated.

{
  "id": "evt_053_example",
  "object": "event",
  "type": "checkout_link.updated",
  "created": 1709945520,
  "livemode": false,
  "data": {
    "object": {
      "id": "clink_test_1234567890",
      "object": "checkout_link",
      "url": "https://pay.example.com/c/clink_test_1234567890",
      "active": false,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Order Events

`order.canceled`

Occurs when an order is canceled.

{
  "id": "evt_054_example",
  "object": "event",
  "type": "order.canceled",
  "created": 1709945580,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "canceled",
      "total_amount": 7500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.created`

Occurs when a new order is created.

{
  "id": "evt_055_example",
  "object": "event",
  "type": "order.created",
  "created": 1709945640,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "open",
      "total_amount": 7500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.fulfilled`

Occurs when an order is fully fulfilled.

{
  "id": "evt_056_example",
  "object": "event",
  "type": "order.fulfilled",
  "created": 1709945700,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "fulfilled",
      "fulfillment_status": "fulfilled",
      "total_amount": 7500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.paid`

Occurs when payment for an order is confirmed.

{
  "id": "evt_057_example",
  "object": "event",
  "type": "order.paid",
  "created": 1709945760,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "open",
      "payment_status": "paid",
      "total_amount": 7500,
      "currency": "usd",
      "payment_intent": "pi_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.payment_failed`

Occurs when payment for an order fails.

{
  "id": "evt_058_example",
  "object": "event",
  "type": "order.payment_failed",
  "created": 1709945820,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "open",
      "payment_status": "failed",
      "total_amount": 7500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.refunded`

Occurs when an order is refunded.

{
  "id": "evt_059_example",
  "object": "event",
  "type": "order.refunded",
  "created": 1709945880,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "open",
      "payment_status": "refunded",
      "total_amount": 7500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.returned`

Occurs when an order is returned.

{
  "id": "evt_060_example",
  "object": "event",
  "type": "order.returned",
  "created": 1709945940,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "returned",
      "total_amount": 7500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`order.updated`

Occurs when an order is updated.

{
  "id": "evt_061_example",
  "object": "event",
  "type": "order.updated",
  "created": 1709946000,
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_test_1234567890",
      "object": "order",
      "status": "open",
      "total_amount": 8500,
      "currency": "usd",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Fulfillment Events

`fulfillment.canceled`

Occurs when a fulfillment is canceled.

{
  "id": "evt_062_example",
  "object": "event",
  "type": "fulfillment.canceled",
  "created": 1709946060,
  "livemode": false,
  "data": {
    "object": {
      "id": "ful_test_1234567890",
      "object": "fulfillment",
      "order_id": "ord_test_1234567890",
      "status": "canceled",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`fulfillment.created`

Occurs when a fulfillment is created for an order.

{
  "id": "evt_063_example",
  "object": "event",
  "type": "fulfillment.created",
  "created": 1709946120,
  "livemode": false,
  "data": {
    "object": {
      "id": "ful_test_1234567890",
      "object": "fulfillment",
      "order_id": "ord_test_1234567890",
      "status": "pending",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`fulfillment.delivered`

Occurs when a fulfillment is delivered.

{
  "id": "evt_064_example",
  "object": "event",
  "type": "fulfillment.delivered",
  "created": 1709946180,
  "livemode": false,
  "data": {
    "object": {
      "id": "ful_test_1234567890",
      "object": "fulfillment",
      "order_id": "ord_test_1234567890",
      "status": "delivered",
      "tracking_number": "TRACK123456",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`fulfillment.shipped`

Occurs when a fulfillment is shipped.

{
  "id": "evt_065_example",
  "object": "event",
  "type": "fulfillment.shipped",
  "created": 1709946240,
  "livemode": false,
  "data": {
    "object": {
      "id": "ful_test_1234567890",
      "object": "fulfillment",
      "order_id": "ord_test_1234567890",
      "status": "shipped",
      "tracking_number": "TRACK123456",
      "tracking_url": "https://track.example.com/TRACK123456",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`fulfillment.updated`

Occurs when a fulfillment is updated.

{
  "id": "evt_066_example",
  "object": "event",
  "type": "fulfillment.updated",
  "created": 1709946300,
  "livemode": false,
  "data": {
    "object": {
      "id": "ful_test_1234567890",
      "object": "fulfillment",
      "order_id": "ord_test_1234567890",
      "status": "pending",
      "tracking_number": "TRACK123456",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Inventory Item Events

`inventory_item.updated`

Occurs when an inventory item is updated.

{
  "id": "evt_067_example",
  "object": "event",
  "type": "inventory_item.updated",
  "created": 1709946360,
  "livemode": false,
  "data": {
    "object": {
      "id": "inv_test_1234567890",
      "object": "inventory_item",
      "variant_id": "var_test_1234567890",
      "tracked": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Inventory Level Events

`inventory_level.updated`

Occurs when an inventory level is updated.

{
  "id": "evt_068_example",
  "object": "event",
  "type": "inventory_level.updated",
  "created": 1709946420,
  "livemode": false,
  "data": {
    "object": {
      "id": "invl_test_1234567890",
      "object": "inventory_level",
      "inventory_item_id": "inv_test_1234567890",
      "available": 42,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Collection Events

`collection.created`

Occurs when a new collection is created.

{
  "id": "evt_069_example",
  "object": "event",
  "type": "collection.created",
  "created": 1709946480,
  "livemode": false,
  "data": {
    "object": {
      "id": "col_test_1234567890",
      "object": "collection",
      "title": "Summer Sale",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`collection.deleted`

Occurs when a collection is deleted.

{
  "id": "evt_070_example",
  "object": "event",
  "type": "collection.deleted",
  "created": 1709946540,
  "livemode": false,
  "data": {
    "object": {
      "id": "col_test_1234567890",
      "object": "collection",
      "deleted": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`collection.updated`

Occurs when a collection is updated.

{
  "id": "evt_071_example",
  "object": "event",
  "type": "collection.updated",
  "created": 1709946600,
  "livemode": false,
  "data": {
    "object": {
      "id": "col_test_1234567890",
      "object": "collection",
      "title": "Summer Sale 2025",
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Promotion Events

`promotion.created`

Occurs when a new promotion is created.

{
  "id": "evt_072_example",
  "object": "event",
  "type": "promotion.created",
  "created": 1709946660,
  "livemode": false,
  "data": {
    "object": {
      "id": "disc_test_1234567890",
      "object": "promotion",
      "name": "SUMMER20",
      "type": "percentage",
      "value": 2000,
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`promotion.deleted`

Occurs when a promotion is deleted.

{
  "id": "evt_073_example",
  "object": "event",
  "type": "promotion.deleted",
  "created": 1709946720,
  "livemode": false,
  "data": {
    "object": {
      "id": "disc_test_1234567890",
      "object": "promotion",
      "deleted": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`promotion.updated`

Occurs when a promotion is updated.

{
  "id": "evt_074_example",
  "object": "event",
  "type": "promotion.updated",
  "created": 1709946780,
  "livemode": false,
  "data": {
    "object": {
      "id": "disc_test_1234567890",
      "object": "promotion",
      "name": "SUMMER20",
      "type": "percentage",
      "value": 2500,
      "active": true,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Balance Events

`balance.available`

Occurs when the merchant available balance has changed.

{
  "id": "evt_075_example",
  "object": "event",
  "type": "balance.available",
  "created": 1709946840,
  "livemode": false,
  "data": {
    "object": {
      "object": "balance",
      "available": [
        {
          "amount": 500000,
          "currency": "usd"
        }
      ],
      "pending": [
        {
          "amount": 25000,
          "currency": "usd"
        }
      ],
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Payout Events

`payout.canceled`

Occurs when a payout is canceled.

{
  "id": "evt_076_example",
  "object": "event",
  "type": "payout.canceled",
  "created": 1709946900,
  "livemode": false,
  "data": {
    "object": {
      "id": "po_test_1234567890",
      "object": "payout",
      "amount": 100000,
      "currency": "usd",
      "status": "canceled",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payout.created`

Occurs when a payout is created.

{
  "id": "evt_077_example",
  "object": "event",
  "type": "payout.created",
  "created": 1709946960,
  "livemode": false,
  "data": {
    "object": {
      "id": "po_test_1234567890",
      "object": "payout",
      "amount": 100000,
      "currency": "usd",
      "status": "pending",
      "arrival_date": 1700000000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payout.failed`

Occurs when a payout fails.

{
  "id": "evt_078_example",
  "object": "event",
  "type": "payout.failed",
  "created": 1709947020,
  "livemode": false,
  "data": {
    "object": {
      "id": "po_test_1234567890",
      "object": "payout",
      "amount": 100000,
      "currency": "usd",
      "status": "failed",
      "failure_code": "account_closed",
      "failure_message": "The bank account has been closed.",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payout.paid`

Occurs when a payout is marked as paid and funds have arrived.

{
  "id": "evt_079_example",
  "object": "event",
  "type": "payout.paid",
  "created": 1709947080,
  "livemode": false,
  "data": {
    "object": {
      "id": "po_test_1234567890",
      "object": "payout",
      "amount": 100000,
      "currency": "usd",
      "status": "paid",
      "arrival_date": 1700000000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`payout.updated`

Occurs when a payout intermediate state changes (e.g. arrival date adjustment).

{
  "id": "evt_080_example",
  "object": "event",
  "type": "payout.updated",
  "created": 1709947140,
  "livemode": false,
  "data": {
    "object": {
      "id": "po_test_1234567890",
      "object": "payout",
      "amount": 100000,
      "currency": "usd",
      "status": "in_transit",
      "arrival_date": 1700000000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Transfer Events

`transfer.created`

Occurs when a new transfer is created to move funds to a merchant.

{
  "id": "evt_081_example",
  "object": "event",
  "type": "transfer.created",
  "created": 1709947200,
  "livemode": false,
  "data": {
    "object": {
      "id": "tr_test_1234567890",
      "object": "transfer",
      "amount": 4500000,
      "currency": "usd",
      "status": "pending",
      "settlement_batch_id": "sbatch_test_1234567890",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`transfer.reversed`

Occurs when a transfer to a merchant has been reversed (e.g. due to a clawback or settlement reversal).

{
  "id": "evt_082_example",
  "object": "event",
  "type": "transfer.reversed",
  "created": 1709947260,
  "livemode": false,
  "data": {
    "object": {
      "id": "tr_test_1234567890",
      "object": "transfer",
      "amount": 4500000,
      "currency": "usd",
      "status": "reversed",
      "reversed_at": 1700000000,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`transfer.updated`

Occurs when a transfer is updated (status, arrival date, or metadata).

{
  "id": "evt_083_example",
  "object": "event",
  "type": "transfer.updated",
  "created": 1709947320,
  "livemode": false,
  "data": {
    "object": {
      "id": "tr_test_1234567890",
      "object": "transfer",
      "amount": 4500000,
      "currency": "usd",
      "status": "paid",
      "arrival_date": "2024-03-08",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Settlement Events

`settlement.batch.completed`

Occurs when a settlement batch has completed processing.

{
  "id": "evt_084_example",
  "object": "event",
  "type": "settlement.batch.completed",
  "created": 1709947380,
  "livemode": false,
  "data": {
    "object": {
      "id": "sbatch_test_1234567890",
      "object": "settlement_batch",
      "status": "completed",
      "total_amount": 5000000,
      "currency": "usd",
      "transaction_count": 127,
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Merchant Events

`merchant.verification.approved`

Occurs when merchant identity verification is approved.

{
  "id": "evt_085_example",
  "object": "event",
  "type": "merchant.verification.approved",
  "created": 1709947440,
  "livemode": false,
  "data": {
    "object": {
      "id": "mer_test_1234567890",
      "object": "merchant",
      "verification_status": "approved",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`merchant.verification.rejected`

Occurs when merchant identity verification is rejected.

{
  "id": "evt_086_example",
  "object": "event",
  "type": "merchant.verification.rejected",
  "created": 1709947500,
  "livemode": false,
  "data": {
    "object": {
      "id": "mer_test_1234567890",
      "object": "merchant",
      "verification_status": "rejected",
      "rejection_reason": "document_unreadable",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

`merchant.verification.started`

Occurs when merchant identity verification has been initiated.

{
  "id": "evt_087_example",
  "object": "event",
  "type": "merchant.verification.started",
  "created": 1709947560,
  "livemode": false,
  "data": {
    "object": {
      "id": "mer_test_1234567890",
      "object": "merchant",
      "verification_status": "pending",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Conversion Tracking Events

`conversion_tracking.config.error`

Occurs when a conversion tracking configuration encounters an error (e.g., expired access token).

{
  "id": "evt_088_example",
  "object": "event",
  "type": "conversion_tracking.config.error",
  "created": 1709947620,
  "livemode": false,
  "data": {
    "object": {
      "id": "capi_test_1234567890",
      "object": "conversion_api_config",
      "provider": "meta",
      "pixel_id": "123456789",
      "status": "error",
      "last_error": "Invalid OAuth 2.0 access token (HTTP 401)",
      "merchant_id": "mer_test_1234567890"
    }
  }
}

Best Practices

Verify signatures

Always verify the Fluveo-Signature header before processing any webhook event.

Return 2xx quickly

Respond with a 200 status code within 30 seconds. Process events asynchronously if needed.

Handle duplicates

Use the Webhook-Id header (or the event id field) to deduplicate. We may send the same event more than once during retries.

Use event type filtering

Only subscribe to the event types you need to reduce unnecessary traffic.

Get Started

Payments

Catalog

Core Concepts

Reference

Documentation Index

​Payload Structure

​Verifying Webhook Signatures

​Verification Example

​Payment Intent Events

​payment_intent.canceled

​payment_intent.created

​payment_intent.payment_failed

​payment_intent.requires_action

​payment_intent.succeeded

​Charge Events

​charge.failed

​charge.refunded

​charge.succeeded

​Refund Events

​refund.created

​refund.failed

​refund.updated

​Dispute Events

​charge.dispute.closed

​charge.dispute.created

​charge.dispute.updated

​dispute.closed

​dispute.created

​dispute.evidence.required

​dispute.updated

​Customer Events

​customer.created

​customer.deleted

​customer.updated

​Setup Intent Events

​setup_intent.created

​setup_intent.setup_failed

​setup_intent.succeeded

​Subscription Events

​customer.subscription.created

​customer.subscription.deleted

​customer.subscription.past_due

​customer.subscription.resumed

​customer.subscription.trial_will_end

​customer.subscription.updated

​subscription.created

​subscription.deleted

​subscription.past_due

​subscription.resumed

​subscription.trial_will_end

​subscription.updated

​Invoice Events

​invoice.created

​invoice.finalized

​invoice.marked_uncollectible

​invoice.paid

​invoice.payment_failed

​invoice.upcoming

​invoice.voided

​Product Events

​product.created

​product.deleted

​product.updated

​Price Events

​price.created

​price.deleted

​price.updated

​Checkout Session Events

​checkout.session.completed

​checkout.session.expired

​Checkout Link Events

​checkout_link.created

​checkout_link.updated

​Order Events

​order.canceled

​order.created

​order.fulfilled

​order.paid

​order.payment_failed

Payload Structure

Verifying Webhook Signatures

Verification Example

Payment Intent Events

`payment_intent.canceled`

`payment_intent.created`

`payment_intent.payment_failed`

`payment_intent.requires_action`

`payment_intent.succeeded`

Charge Events

`charge.failed`

`charge.refunded`

`charge.succeeded`

Refund Events

`refund.created`

`refund.failed`

`refund.updated`

Dispute Events

`charge.dispute.closed`

`charge.dispute.created`

`charge.dispute.updated`

`dispute.closed`

`dispute.created`

`dispute.evidence.required`

`dispute.updated`

Customer Events

`customer.created`

`customer.deleted`

`customer.updated`

Setup Intent Events

`setup_intent.created`

`setup_intent.setup_failed`

`setup_intent.succeeded`

Subscription Events

`customer.subscription.created`

`customer.subscription.deleted`

`customer.subscription.past_due`

`customer.subscription.resumed`

`customer.subscription.trial_will_end`

`customer.subscription.updated`

`subscription.created`

`subscription.deleted`

`subscription.past_due`

`subscription.resumed`

`subscription.trial_will_end`

`subscription.updated`

Invoice Events

`invoice.created`

`invoice.finalized`

`invoice.marked_uncollectible`

`invoice.paid`

`invoice.payment_failed`

`invoice.upcoming`

`invoice.voided`

Product Events

`product.created`

`product.deleted`

`product.updated`

Price Events

`price.created`

`price.deleted`

`price.updated`

Checkout Session Events

`checkout.session.completed`

`checkout.session.expired`

Checkout Link Events

`checkout_link.created`

`checkout_link.updated`

Order Events

`order.canceled`

`order.created`

`order.fulfilled`

`order.paid`

`order.payment_failed`

`order.refunded`

`order.returned`

`order.updated`

Fulfillment Events

`fulfillment.canceled`

`fulfillment.created`