Webhook event types reference

Complete reference for every Marlin webhook event type — when each fires, what the data payload contains, and sample JSON for key events.

Marlin emits a webhook event each time a significant state change occurs on a resource. Your handler receives the full resource object inside the data field so you have all the information you need without a follow-up API call.

The type field on every event follows the pattern <resource>.<action>. The sections below describe each event group, when each event fires, and what the data field contains.

Invoice events

Marlin fires invoice events when an invoice moves through its lifecycle — from creation to payment, void, or becoming overdue.

Event	Fires when
invoice.created	A new invoice is created (draft or open)
invoice.paid	The invoice is fully settled on-chain
invoice.voided	The invoice is voided before payment
invoice.overdue	The invoice passes its dueDate without payment

The data payload for all invoice events is a full Invoice object:

Field	Type	Description
id	string	Invoice ID
object	"invoice"	Always "invoice"
customerId	string	ID of the customer billed
subscriptionId	string | null	Linked subscription, if any
status	string	draft, open, paid, void, uncollectible, or processing
currency	string	Currency code (e.g. "USDC")
amount	number	Total invoice amount in the smallest unit
amountPaid	number	Amount received so far
amountRemaining	number	Outstanding balance
description	string | null	Invoice-level description
memo	string | null	Internal memo
dueDate	string | null	ISO 8601 due date
paidAt	string | null	ISO 8601 timestamp of full payment
voidedAt	string | null	ISO 8601 timestamp of void
lineItems	InvoiceLineItem[]	Array of line items (description, quantity, unitAmount, amount)
metadata	Record<string, string>	Custom key/value pairs
paymentUrl	string | null	Hosted checkout URL
transactionSignature	string | null	Solana transaction signature after payment
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-updated timestamp

Sample payload — invoice.paid

{
  "id": "evt_01hwabcdef123456",
  "object": "event",
  "type": "invoice.paid",
  "createdAt": "2025-05-06T14:23:00Z",
  "data": {
    "id": "inv_01hwabcdef789012",
    "object": "invoice",
    "customerId": "cus_01hwabcdef345678",
    "subscriptionId": "sub_01hwabcdef901234",
    "status": "paid",
    "currency": "USDC",
    "amount": 4900,
    "amountPaid": 4900,
    "amountRemaining": 0,
    "description": "Pro Plan — May 2025",
    "memo": null,
    "dueDate": "2025-05-15T00:00:00Z",
    "paidAt": "2025-05-06T14:22:58Z",
    "voidedAt": null,
    "lineItems": [
      {
        "description": "Pro Plan — May 2025",
        "quantity": 1,
        "unitAmount": 4900,
        "amount": 4900
      }
    ],
    "metadata": {},
    "paymentUrl": "https://pay.marlin.dev/inv_01hwabcdef789012",
    "transactionSignature": "5KKsLn...Tq2Z",
    "createdAt": "2025-05-01T00:00:00Z",
    "updatedAt": "2025-05-06T14:22:58Z"
  }
}

Subscription events

Marlin fires subscription events when a subscription’s status changes. Use these events to gate feature access, provision or deprovision resources, and send in-app notifications.

Event	Fires when
subscription.created	A new subscription is created (may still be in trial)
subscription.activated	The subscription becomes active — trial ended or first invoice paid
subscription.paused	The subscription is paused by the merchant or customer
subscription.resumed	A paused subscription is reactivated
subscription.canceled	The subscription is canceled (immediately or at period end)
subscription.past_due	A renewal invoice was not paid by the due date

The data payload for all subscription events is a full Subscription object:

Field	Type	Description
id	string	Subscription ID
object	"subscription"	Always "subscription"
customerId	string	ID of the subscribed customer
planId	string	ID of the billing plan
status	string	active, paused, canceled, past_due, trialing, or incomplete
currentPeriodStart	string	ISO 8601 start of the current billing period
currentPeriodEnd	string	ISO 8601 end of the current billing period
cancelAtPeriodEnd	boolean	Whether cancellation is scheduled for period end
canceledAt	string | null	ISO 8601 timestamp of cancellation
pausedAt	string | null	ISO 8601 timestamp when paused
trialStart	string | null	ISO 8601 trial start
trialEnd	string | null	ISO 8601 trial end
metadata	Record<string, string>	Custom key/value pairs
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-updated timestamp

Sample payload — subscription.activated

{
  "id": "evt_01hwabcdef567890",
  "object": "event",
  "type": "subscription.activated",
  "createdAt": "2025-05-06T09:00:00Z",
  "data": {
    "id": "sub_01hwabcdef901234",
    "object": "subscription",
    "customerId": "cus_01hwabcdef345678",
    "planId": "plan_01hwabcdef112233",
    "status": "active",
    "currentPeriodStart": "2025-05-06T09:00:00Z",
    "currentPeriodEnd": "2025-06-06T09:00:00Z",
    "cancelAtPeriodEnd": false,
    "canceledAt": null,
    "pausedAt": null,
    "trialStart": "2025-04-29T09:00:00Z",
    "trialEnd": "2025-05-06T09:00:00Z",
    "metadata": { "plan_tier": "pro" },
    "createdAt": "2025-04-29T09:00:00Z",
    "updatedAt": "2025-05-06T09:00:00Z"
  }
}

Customer events

Marlin fires customer events when a customer record is created or updated. Use these to sync customer data to your CRM or database.

Event	Fires when
customer.created	A new customer is created via the API or dashboard
customer.updated	Any field on the customer (email, name, walletAddress, metadata) changes

The data payload for both events is a full Customer object:

Field	Type	Description
id	string	Customer ID
object	"customer"	Always "customer"
email	string	Customer email address
name	string | null	Display name
walletAddress	string | null	Solana wallet address for on-chain payments
metadata	Record<string, string>	Custom key/value pairs
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-updated timestamp

Payment events

Marlin fires payment events as an on-chain payment moves through confirmation. These events give you finer-grained visibility into the settlement process before the corresponding invoice is marked paid.

Event	Fires when
payment.received	A transaction is detected on-chain (not yet finalized)
payment.confirmed	The transaction reaches sufficient confirmation depth and the payment is finalized

The data payload for payment events contains the associated invoice ID, the Solana transaction signature, the amount received, and the currency:

Field	Type	Description
invoiceId	string	ID of the invoice being paid
transactionSignature	string	Solana transaction signature
amount	number	Amount received in the smallest currency unit
currency	string	Currency code (e.g. "USDC")

Listen to payment.confirmed (not payment.received) before fulfilling orders or unlocking access. A payment.received event indicates the transaction was seen but is not yet finalized.