Webhooks

What is a webhook?

Creem uses webhooks to push real-time notifications to you about your payments and subscriptions. All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:

Automatically enable access to a user after a successful payment
Automatically remove access to a user after a canceled subscription
Confirm that a payment has been received by the same customer that initiated it.

In case webhooks are not successfully received by your endpoint, Creem automatically retries the request with a progressive backoff. There are 5 attempts in total — the initial delivery, then retries after 30 seconds, 5 minutes, 30 minutes and 6 hours. Events are not retried after 24 hours, even if attempts remain. Because the same event can be delivered more than once, your handler should be idempotent. You can also resend webhook events manually from your Merchant dashboard under Developers section.

Steps to receive a webhook

You can start receiving real-time events in your app using the steps:

Create a local endpoint to receive requests
Register your development webhook endpoint on the Developers tab of the Creem dashboard
Test that your webhook endpoint is working properly using the test environment
Deploy your webhook endpoint to production
Register your production webhook endpoint on Creem live dashboard

On Next.js projects, the @creem_io/nextjs adapter exports a Webhook helper that verifies signatures and surfaces typed lifecycle callbacks. Use it as your default implementation before falling back to manual parsing.

1. Create a local endpoint to receive requests

In your local application, create a new route that can accept POST requests.

// app/api/webhook/creem/route.ts
import { Webhook } from "@creem_io/nextjs";

export const POST = Webhook({
  webhookSecret: process.env.CREEM_WEBHOOK_SECRET!,
  onCheckoutCompleted: async ({ customer, product }) => {
    console.log(`${customer.email} purchased ${product.name}`);
  },
  onGrantAccess: async ({ customer, metadata }) => {
    const userId = metadata?.referenceId as string;
    await grantAccess(userId, customer.email);
  },
  onRevokeAccess: async ({ customer, metadata }) => {
    const userId = metadata?.referenceId as string;
    await revokeAccess(userId, customer.email);
  },
});

import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== "POST") {
    return res.status(405).end();
  }

  const payload = req.body;
  console.log(payload);
  res.status(200).end();
}

On receiving an event, you should respond with an HTTP 200 OK to signal to Creem that the event was successfully delivered.

2. Register your development webhook endpoint

The quickest way to receive events locally is the Creem CLI: it registers a temporary endpoint for you and forwards events to your server with the real signature header, no public URL needed.

creem listen --forward-to http://localhost:3000/api/webhooks

Otherwise, register your publicly accessible HTTPS URL in the Creem dashboard.

You can create a tunnel to your localhost server using a tool like ngrok. For example: https://8733-191-204-177-89.sa.ngrok.io/api/webhooks

3. Test that your webhook endpoint is working properly

Create a few test payments to check that your webhook endpoint is receiving the events.

4. Deploy your webhook endpoint

After you’re done testing, deploy your webhook endpoint to production.

5. Register your production webhook endpoint

Once your webhook endpoint is deployed to production, you can register it in the Creem dashboard.

Register endpoints programmatically

Every step above can also be done from code, so an integration (or an AI agent) can provision its own endpoint. The public API exposes webhook endpoint management under /v1/webhooks; the same operations are available in the TypeScript SDK, the CLI and the MCP server. Keys need the webhooks:read or webhooks:write scope.

import { Creem } from "creem";

const creem = new Creem({ apiKey: process.env.CREEM_API_KEY });

// The signing secret is returned on create only. Store it, then verify
// every delivery with it (see "Webhook Signatures" below).
const webhook = await creem.webhooks.create({
  url: "https://example.com/webhooks/creem",
  name: "Production billing events",
  events: ["checkout.completed", "subscription.paid"],
});
console.log(webhook.id, webhook.secret);

// Pause deliveries without losing the configuration.
await creem.webhooks.update(webhook.id, { status: "disabled" });

// Fetch the secret again later.
const { secret } = await creem.webhooks.getSecret(webhook.id);

creem webhooks create --url https://example.com/webhooks/creem --event checkout.completed --event subscription.paid --json
creem webhooks list --json
creem webhooks update wh_123 --status disabled --json
creem webhooks secret wh_123 --json
creem webhooks delete wh_123 --yes --json

An empty events list subscribes the endpoint to every event type. See the Webhooks API reference for the full contract.

Network Configuration

Creem does not provide static source IP addresses for outbound webhooks in either Test Mode or production. If your firewall or WAF protects the webhook endpoint, do not rely on source-IP allowlists as the authentication mechanism. Keep the endpoint reachable over HTTPS and verify every request with the creem-signature header.

Bot protection and WAF products can challenge webhook deliveries because webhooks are automated server-to-server requests. If this happens, add a route-level exception or skip rule for your webhook endpoint. On Cloudflare specifically, Bot Fight Mode cannot be skipped with custom rules; disable it or use Super Bot Fight Mode or Bot Management with a skip rule.

Webhook Signatures

How to verify Creem signature?

Creem signature is sent in the creem-signature header of the webhook request. The signature is generated using the HMAC-SHA256 algorithm with the webhook secret as the key, and the request payload as the message.

Sample Webhook Header

{
'creem-signature': 'dd7bdd2cf1f6bac6e171c6c508c157b7cd3cc1fd196394277fb59ba0bdd9b87b'
}

Use the TypeScript SDK to verify the signature before processing the event payload.

You can find your webhook secret on the Developers>Webhook page.

import { verifyWebhookSignature } from "creem/webhooks";

await verifyWebhookSignature(rawBody, request.headers, {
  secret: process.env.CREEM_WEBHOOK_SECRET!,
});

If you are not using the SDK, generate the signature with HMAC-SHA256 using the raw request body and compare it with the creem-signature header.

import * as crypto from 'crypto';

  generateSignature(payload: string, secret: string): string {
    const computedSignature = crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
    return computedSignature;
  }

In the code snippet above, the payload is the request body, and the secret is the webhook secret. Simply compare the generated Signature with the one received on the header to complete the verification process.

Event Types

List of supported event types and their payloads.

checkout.completed

A checkout session was completed, returning all the information about the payment and the order created.

Sample Request Body

{
  "id": "evt_5WHHcZPv7VS0YUsberIuOz",
  "eventType": "checkout.completed",
  "created_at": 1728734325927,
  "object": {
    "id": "ch_4l0N34kxo16AhRKUHFUuXr",
    "object": "checkout",
    "request_id": "my-request-id",
    "order": {
      "id": "ord_4aDwWXjMLpes4Kj4XqNnUA",
      "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "product": "prod_d1AY2Sadk9YAvLI0pj97f",
      "amount": 1000,
      "currency": "EUR",
      "status": "paid",
      "type": "recurring",
      "created_at": "2024-10-12T11:58:33.097Z",
      "updated_at": "2024-10-12T11:58:33.097Z",
      "mode": "local"
    },
    "product": {
      "id": "prod_d1AY2Sadk9YAvLI0pj97f",
      "name": "Monthly",
      "description": "Monthly",
      "image_url": null,
      "price": 1000,
      "currency": "EUR",
      "billing_type": "recurring",
      "billing_period": "every-month",
      "status": "active",
      "tax_mode": "exclusive",
      "tax_category": "saas",
      "default_success_url": "",
      "created_at": "2024-10-11T11:50:00.182Z",
      "updated_at": "2024-10-11T11:50:00.182Z",
      "mode": "local"
    },
    "customer": {
      "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "object": "customer",
      "email": "customer@emaildomain",
      "name": "Tester Test",
      "country": "NL",
      "created_at": "2024-10-11T09:16:48.557Z",
      "updated_at": "2024-10-11T09:16:48.557Z",
      "mode": "local"
    },
    "subscription": {
      "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
      "object": "subscription",
      "product": "prod_d1AY2Sadk9YAvLI0pj97f",
      "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "collection_method": "charge_automatically",
      "status": "active",
      "canceled_at": null,
      "created_at": "2024-10-12T11:58:45.425Z",
      "updated_at": "2024-10-12T11:58:45.425Z",
      "metadata": {
        "custom_data": "mycustom data",
        "internal_customer_id": "internal_customer_id"
      },
      "mode": "local"
    },
    "license_keys": [
      {
        "id": "lk_2wMk1RtYqPnZ7bVxCdEfGh",
        "object": "license",
        "product_id": "prod_d1AY2Sadk9YAvLI0pj97f",
        "key": "ABCDE-FGHIJ-KLMNO-PQRST-UVWXY",
        "status": "inactive",
        "activation": 0,
        "activation_limit": 1,
        "expires_at": null,
        "created_at": "2024-10-12T11:58:33.097Z",
        "instance": null,
        "mode": "local"
      }
    ],
    "custom_fields": [],
    "status": "completed",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  }
}

License keys

If the purchased product issues license keys, the checkout object also carries a license_keys array, as shown in the sample above.

license_keys is only present when the order actually issued license keys. For a product without a license key feature the field is omitted entirely — check whether it is present rather than expecting an empty array.

Each entry is a license object, not a key string:

Field	Type	Description
`id`	string	Unique identifier for the license, prefixed with `lk_`.
`object`	string	Always `license`.
`product_id`	string	The product the license was issued for.
`key`	string	The license key itself: five groups of five uppercase alphanumeric characters, for example `ABCDE-FGHIJ-KLMNO-PQRST-UVWXY`.
`status`	string	One of `inactive`, `active`, `expired`, or `disabled`. A key stays `inactive` until its first successful activation.
`activation`	number	Number of times the key has been activated so far.
`activation_limit`	number \| null	Maximum number of activations allowed. `null` means unlimited.
`expires_at`	string \| null	ISO 8601 expiry date. `null` means the key does not expire.
`created_at`	string	ISO 8601 date the license was created.
`instance`	object \| null	The associated license instance, when one exists.
`mode`	string	The environment the license belongs to.

You do not need a real purchase to see this shape. In the dashboard go to Settings → Webhooks, open a webhook and use Send test event — the checkout.completed payload it delivers includes a populated license_keys array.

One key is issued per license key feature on the product, multiplied by the number of units purchased — a three-unit order of a keyed product delivers three entries. Always treat license_keys as a list, never as a single key. For issuing and managing keys, see Licenses.

subscription.active

Received when a new subscription is created, the payment was successful and Creem collected the payment creating a new subscription object in your account. Use only for synchronization, we encourage using subscription.paid for activating access.

Sample Request Body

{
  "id": "evt_6EptlmjazyGhEPiNQ5f4lz",
  "eventType": "subscription.active",
  "created_at": 1728734325927,
  "object": {
      "id": "sub_21lfZb67szyvMiXnm6SVi0",
      "object": "subscription",
      "product": {
          "id": "prod_AnVJ11ujp7x953ARpJvAF",
          "name": "My Product - Product 01",
          "description": "Test my product",
          "image_url": null,
          "price": 10000,
          "currency": "EUR",
          "billing_type": "recurring",
          "billing_period": "every-month",
          "status": "active",
          "tax_mode": "inclusive",
          "tax_category": "saas",
          "default_success_url": "",
          "created_at": "2024-09-16T16:12:09.813Z",
          "updated_at": "2024-09-16T16:12:09.813Z",
          "mode": "local"
      },
      "customer": {
          "id": "cust_3biFPNt4Cz5YRDSdIqs7kc",
          "object": "customer",
          "email": "customer@emaildomain",
          "name": "Tester Test",
          "country": "SE",
          "created_at": "2024-09-16T16:13:39.265Z",
          "updated_at": "2024-09-16T16:13:39.265Z",
          "mode": "local"
      },
      "collection_method": "charge_automatically",
      "status": "active",
      "canceled_at": "2024-09-16T19:40:41.984Z",
      "created_at": "2024-09-16T19:40:41.984Z",
      "updated_at": "2024-09-16T19:40:42.121Z",
      "mode": "local"
  }
}

subscription.paid

A subscription transaction was paid by the customer

Sample Request Body

{
  "id": "evt_21mO1jWmU2QHe7u2oFV7y1",
  "eventType": "subscription.paid",
  "created_at": 1728734327355,
  "object": {
    "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "object": "subscription",
    "product": {
      "id": "prod_d1AY2Sadk9YAvLI0pj97f",
      "name": "Monthly",
      "description": "Monthly",
      "image_url": null,
      "price": 1000,
      "currency": "EUR",
      "billing_type": "recurring",
      "billing_period": "every-month",
      "status": "active",
      "tax_mode": "exclusive",
      "tax_category": "saas",
      "default_success_url": "",
      "created_at": "2024-10-11T11:50:00.182Z",
      "updated_at": "2024-10-11T11:50:00.182Z",
      "mode": "local"
    },
    "customer": {
      "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "object": "customer",
      "email": "customer@emaildomain",
      "name": "Tester Test",
      "country": "NL",
      "created_at": "2024-10-11T09:16:48.557Z",
      "updated_at": "2024-10-11T09:16:48.557Z",
      "mode": "local"
    },
    "collection_method": "charge_automatically",
    "status": "active",
    "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
    "last_transaction_date": "2024-10-12T11:58:47.109Z",
    "next_transaction_date": "2024-11-12T11:58:38.000Z",
    "current_period_start_date": "2024-10-12T11:58:38.000Z",
    "current_period_end_date": "2024-11-12T11:58:38.000Z",
    "canceled_at": null,
    "created_at": "2024-10-12T11:58:45.425Z",
    "updated_at": "2024-10-12T11:58:45.425Z",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  }
}

subscription.canceled

The subscription was canceled by the merchant or by the customer.

Sample Request Body

{
  "id": "evt_2iGTc600qGW6FBzloh2Nr7",
  "eventType": "subscription.canceled",
  "created_at": 1728734337932,
  "object": {
    "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "object": "subscription",
    "product": {
      "id": "prod_d1AY2Sadk9YAvLI0pj97f",
      "name": "Monthly",
      "description": "Monthly",
      "image_url": null,
      "price": 1000,
      "currency": "EUR",
      "billing_type": "recurring",
      "billing_period": "every-month",
      "status": "active",
      "tax_mode": "exclusive",
      "tax_category": "saas",
      "default_success_url": "",
      "created_at": "2024-10-11T11:50:00.182Z",
      "updated_at": "2024-10-11T11:50:00.182Z",
      "mode": "local"
    },
    "customer": {
      "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "object": "customer",
      "email": "customer@emaildomain",
      "name": "Tester Test",
      "country": "NL",
      "created_at": "2024-10-11T09:16:48.557Z",
      "updated_at": "2024-10-11T09:16:48.557Z",
      "mode": "local"
    },
    "collection_method": "charge_automatically",
    "status": "canceled",
    "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
    "last_transaction_date": "2024-10-12T11:58:47.109Z",
    "current_period_start_date": "2024-10-12T11:58:38.000Z",
    "current_period_end_date": "2024-11-12T11:58:38.000Z",
    "canceled_at": "2024-10-12T11:58:57.813Z",
    "created_at": "2024-10-12T11:58:45.425Z",
    "updated_at": "2024-10-12T11:58:57.827Z",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  }
}

subscription.scheduled_cancel

The subscription was scheduled for cancellation at the end of the current billing period. The subscription remains active until current_period_end_date, after which it transitions to canceled. This event is triggered when a customer or merchant requests cancellation but opts to cancel at the end of the period rather than immediately. You can use this event to notify the customer about the upcoming cancellation or to offer retention incentives. The subscription can be resumed before the period ends using the Resume Subscription endpoint, which will change the status back to active and prevent the cancellation.

Sample Request Body

{
  "id": "evt_4RfTc700qGW6FBzloh3Ms8",
  "eventType": "subscription.scheduled_cancel",
  "created_at": 1728734337932,
  "object": {
    "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "object": "subscription",
    "product": {
      "id": "prod_d1AY2Sadk9YAvLI0pj97f",
      "name": "Monthly",
      "description": "Monthly",
      "image_url": null,
      "price": 1000,
      "currency": "EUR",
      "billing_type": "recurring",
      "billing_period": "every-month",
      "status": "active",
      "tax_mode": "exclusive",
      "tax_category": "saas",
      "default_success_url": "",
      "created_at": "2024-10-11T11:50:00.182Z",
      "updated_at": "2024-10-11T11:50:00.182Z",
      "mode": "local"
    },
    "customer": {
      "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "object": "customer",
      "email": "customer@emaildomain",
      "name": "Tester Test",
      "country": "NL",
      "created_at": "2024-10-11T09:16:48.557Z",
      "updated_at": "2024-10-11T09:16:48.557Z",
      "mode": "local"
    },
    "collection_method": "charge_automatically",
    "status": "scheduled_cancel",
    "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
    "last_transaction_date": "2024-10-12T11:58:47.109Z",
    "current_period_start_date": "2024-10-12T11:58:38.000Z",
    "current_period_end_date": "2024-11-12T11:58:38.000Z",
    "canceled_at": null,
    "created_at": "2024-10-12T11:58:45.425Z",
    "updated_at": "2024-10-12T11:59:15.827Z",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  }
}

subscription.past_due

The subscription payment has failed and the subscription is now past due. This occurs when a payment attempt fails (e.g., card declined, insufficient funds). Creem will automatically retry the payment according to the retry schedule. If a retry succeeds, the subscription transitions back to active. If all retries are exhausted, the subscription is canceled.

Sample Request Body

{
  "id": "evt_7HkTd800rHX7GCampi4Nt9",
  "eventType": "subscription.past_due",
  "created_at": 1728734337932,
  "object": {
    "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "object": "subscription",
    "product": {
      "id": "prod_d1AY2Sadk9YAvLI0pj97f",
      "name": "Monthly",
      "description": "Monthly",
      "image_url": null,
      "price": 1000,
      "currency": "EUR",
      "billing_type": "recurring",
      "billing_period": "every-month",
      "status": "active",
      "tax_mode": "exclusive",
      "tax_category": "saas",
      "default_success_url": "",
      "created_at": "2024-10-11T11:50:00.182Z",
      "updated_at": "2024-10-11T11:50:00.182Z",
      "mode": "local"
    },
    "customer": {
      "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
      "object": "customer",
      "email": "customer@emaildomain",
      "name": "Tester Test",
      "country": "NL",
      "created_at": "2024-10-11T09:16:48.557Z",
      "updated_at": "2024-10-11T09:16:48.557Z",
      "mode": "local"
    },
    "collection_method": "charge_automatically",
    "status": "past_due",
    "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
    "last_transaction_date": "2024-10-12T11:58:47.109Z",
    "current_period_start_date": "2024-10-12T11:58:38.000Z",
    "current_period_end_date": "2024-11-12T11:58:38.000Z",
    "canceled_at": null,
    "created_at": "2024-10-12T11:58:45.425Z",
    "updated_at": "2024-11-12T12:05:30.827Z",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  }
}

subscription.unpaid

The subscription moved to the unpaid status after failed payment collection. Treat it like subscription.past_due in payment-recovery UI, and suspend access according to your policy.

Sample Request Body

{
  "id": "evt_h9hBneNdvWvA8hQzIBzDx",
  "eventType": "subscription.unpaid",
  "created_at": 1772265400331,
  "object": {
      "id": "sub_3xx35QzxsnpFiJ3vRB9YKt",
      "object": "subscription",
      "status": "unpaid",
      "product": {
          "id": "prod_L8mMzoYLOOZpMpTBwGw0k",
          "name": "Pro Plan",
          "price": 2999,
          "currency": "USD",
          "billing_type": "recurring",
          "billing_period": "every-month",
          "status": "active",
          "tax_mode": "exclusive",
          "tax_category": "saas",
          "mode": "test"
      },
      "customer": {
          "id": "cust_ubD9UtnJpafXNKQ5UaV0H",
          "object": "customer",
          "email": "customer@example.com",
          "name": "Test Customer",
          "country": "US",
          "mode": "test"
      },
      "collection_method": "charge_automatically",
      "last_transaction_id": "tran_6uBkPewvO7KHjfvGmpin82",
      "current_period_start_date": "2026-02-28T07:56:07.282Z",
      "current_period_end_date": "2026-03-30T07:56:07.282Z",
      "canceled_at": null,
      "metadata": {},
      "mode": "test"
  }
}

subscription.expired

The subscription was expired, given that the current_end_period has been reached without a new payment. Payment retries can happen at this stage, and the subscription status will be terminal only when status is changed to canceled.

Sample Request Body

{
  "id": "evt_V5CxhipUu10BYonO2Vshb",
  "eventType": "subscription.expired",
  "created_at": 1734463872058,
  "object": {
      "id": "sub_7FgHvrOMC28tG5DEemoCli",
      "object": "subscription",
      "product": {
          "id": "prod_3ELsC3Lt97orn81SOdgQI3",
          "name": "Subs",
          "description": "Subs",
          "image_url": null,
          "price": 1200,
          "currency": "EUR",
          "billing_type": "recurring",
          "billing_period": "every-year",
          "status": "active",
          "tax_mode": "exclusive",
          "tax_category": "saas",
          "default_success_url": "",
          "created_at": "2024-12-11T17:33:32.186Z",
          "updated_at": "2024-12-11T17:33:32.186Z",
          "mode": "local"
      },
      "customer": {
          "id": "cust_3y4k2CELGsw7n9Eeeiw2hm",
          "object": "customer",
          "email": "customer@emaildomain",
          "name": "Alec Erasmus",
          "country": "NL",
          "created_at": "2024-12-09T16:09:20.709Z",
          "updated_at": "2024-12-09T16:09:20.709Z",
          "mode": "local"
      },
      "collection_method": "charge_automatically",
      "status": "active",
      "last_transaction_id": "tran_6ZeTvMqMkGdAIIjw5aAcnh",
      "last_transaction_date": "2024-12-16T12:40:12.658Z",
      "next_transaction_date": "2025-12-16T12:39:47.000Z",
      "current_period_start_date": "2024-12-16T12:39:47.000Z",
      "current_period_end_date": "2024-12-16T12:39:47.000Z",
      "canceled_at": null,
      "created_at": "2024-12-16T12:40:05.058Z",
      "updated_at": "2024-12-16T12:40:05.058Z",
      "mode": "local"
  }
}

refund.created

A refund was created by the merchant

Sample Request Body

{
"id": "evt_61eTsJHUgInFw2BQKhTiPV",
"eventType": "refund.created",
"created_at": 1728734351631,
"object": {
  "id": "ref_3DB9NQFvk18TJwSqd0N6bd",
  "object": "refund",
  "status": "succeeded",
  "refund_amount": 1210,
  "refund_currency": "EUR",
  "reason": "requested_by_customer",
  "transaction": {
    "id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
    "object": "transaction",
    "amount": 1000,
    "amount_paid": 1210,
    "currency": "EUR",
    "type": "invoice",
    "tax_country": "NL",
    "tax_amount": 210,
    "status": "refunded",
    "refunded_amount": 1210,
    "order": "ord_4aDwWXjMLpes4Kj4XqNnUA",
    "subscription": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "description": "Subscription payment",
    "period_start": 1728734318000,
    "period_end": 1731412718000,
    "created_at": 1728734327109,
    "mode": "local"
  },
  "subscription": {
    "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "object": "subscription",
    "product": "prod_d1AY2Sadk9YAvLI0pj97f",
    "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
    "collection_method": "charge_automatically",
    "status": "canceled",
    "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
    "last_transaction_date": "2024-10-12T11:58:47.109Z",
    "current_period_start_date": "2024-10-12T11:58:38.000Z",
    "current_period_end_date": "2024-11-12T11:58:38.000Z",
    "canceled_at": "2024-10-12T11:58:57.813Z",
    "created_at": "2024-10-12T11:58:45.425Z",
    "updated_at": "2024-10-12T11:58:57.827Z",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  },
  "checkout": {
    "id": "ch_4l0N34kxo16AhRKUHFUuXr",
    "object": "checkout",
    "request_id": "my-request-id",
    "custom_fields": [],
    "status": "completed",
    "metadata": {
      "custom_data": "mycustom data",
      "internal_customer_id": "internal_customer_id"
    },
    "mode": "local"
  },
  "order": {
    "id": "ord_4aDwWXjMLpes4Kj4XqNnUA",
    "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
    "product": "prod_d1AY2Sadk9YAvLI0pj97f",
    "amount": 1000,
    "currency": "EUR",
    "status": "paid",
    "type": "recurring",
    "created_at": "2024-10-12T11:58:33.097Z",
    "updated_at": "2024-10-12T11:58:33.097Z",
    "mode": "local"
  },
  "customer": {
    "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
    "object": "customer",
    "email": "customer@emaildomain",
    "name": "Tester Test",
    "country": "NL",
    "created_at": "2024-10-11T09:16:48.557Z",
    "updated_at": "2024-10-11T09:16:48.557Z",
    "mode": "local"
  },
  "created_at": 1728734351525,
  "mode": "local"
}
}

dispute.created

A dispute was created by the customer

Sample Request Body

{
  "id": "evt_6mfLDL7P0NYwYQqCrICvDH",
  "eventType": "dispute.created",
  "created_at": 1750941264812,
  "object": {
    "id": "disp_6vSsOdTANP5PhOzuDlUuXE",
    "object": "dispute",
    "amount": 1331,
    "currency": "EUR",
    "transaction": {
      "id": "tran_4Dk8CxWFdceRUQgMFhCCXX",
      "object": "transaction",
      "amount": 1100,
      "amount_paid": 1331,
      "currency": "EUR",
      "type": "invoice",
      "tax_country": "NL",
      "tax_amount": 231,
      "status": "chargeback",
      "refunded_amount": 1331,
      "order": "ord_57bf8042UmG8fFypxZrfnj",
      "subscription": "sub_5sD6zM482uwOaEoyEUDDJs",
      "customer": "cust_OJPZd2GMxgo1MGPNXXBSN",
      "description": "Subscription payment",
      "period_start": 1750941201000,
      "period_end": 1753533201000,
      "created_at": 1750941205659,
      "mode": "sandbox"
    },
    "subscription": {
      "id": "sub_5sD6zM482uwOaEoyEUDDJs",
      "object": "subscription",
      "product": "prod_3EFtQRQ9SNIizK3xwfxZHu",
      "customer": "cust_OJPZd2GMxgo1MGPNXXBSN",
      "collection_method": "charge_automatically",
      "status": "active",
      "current_period_start_date": "2025-06-26T12:33:21.000Z",
      "current_period_end_date": "2025-07-26T12:33:21.000Z",
      "canceled_at": null,
      "created_at": "2025-06-26T12:33:23.589Z",
      "updated_at": "2025-06-26T12:33:26.102Z",
      "mode": "sandbox"
    },
    "checkout": {
      "id": "ch_1bJMvqGGzHIftf4ewLXJeq",
      "object": "checkout",
      "product": "prod_3EFtQRQ9SNIizK3xwfxZHu",
      "units": 1,
      "custom_fields": [
        {
          "key": "testing",
          "text": {
            "value": "asdfasdf",
            "max_length": 255
          },
          "type": "text",
          "label": "Testing",
          "optional": false
        }
      ],
      "status": "completed",
      "mode": "sandbox"
    },
    "order": {
      "object": "order",
      "id": "ord_57bf8042UmG8fFypxZrfnj",
      "customer": "cust_OJPZd2GMxgo1MGPNXXBSN",
      "product": "prod_3EFtQRQ9SNIizK3xwfxZHu",
      "amount": 1100,
      "currency": "EUR",
      "sub_total": 1100,
      "tax_amount": 231,
      "amount_due": 1331,
      "amount_paid": 1331,
      "status": "paid",
      "type": "recurring",
      "transaction": "tran_4Dk8CxWFdceRUQgMFhCCXX",
      "created_at": "2025-06-26T12:32:41.395Z",
      "updated_at": "2025-06-26T12:32:41.395Z",
      "mode": "sandbox"
    },
    "customer": {
      "id": "cust_OJPZd2GMxgo1MGPNXXBSN",
      "object": "customer",
      "email": "customer@emaildomain",
      "name": "Alec Erasmus",
      "country": "NL",
      "created_at": "2025-02-05T10:11:01.146Z",
      "updated_at": "2025-02-05T10:11:01.146Z",
      "mode": "sandbox"
    },
    "created_at": 1750941264728,
    "mode": "local"
  }
}

subscription.update

A subscription object was updated

Sample Request Body

{
"id": "evt_5pJMUuvqaqvttFVUvtpY32",
"eventType": "subscription.update",
"created_at": 1737890536421,
"object": {
  "id": "sub_2qAuJgWmXhXHAuef9k4Kur",
  "object": "subscription",
  "product": {
    "id": "prod_1dP15yoyogQe2seEt1Evf3",
    "name": "Monthly Sub",
    "description": "Test Test",
    "image_url": null,
    "price": 1000,
    "currency": "EUR",
    "billing_type": "recurring",
    "billing_period": "every-month",
    "status": "active",
    "tax_mode": "exclusive",
    "tax_category": "saas",
    "default_success_url": "",
    "created_at": "2025-01-26T11:17:16.082Z",
    "updated_at": "2025-01-26T11:17:16.082Z",
    "mode": "local"
  },
  "customer": {
    "id": "cust_2fQZKKUZqtNhH2oDWevQkW",
    "object": "customer",
    "email": "customer@emaildomain",
    "name": "John Doe",
    "country": "NL",
    "created_at": "2025-01-26T11:18:24.071Z",
    "updated_at": "2025-01-26T11:18:24.071Z",
    "mode": "local"
  },
  "items": [
    {
      "object": "subscription_item",
      "id": "sitem_3QWlqRbAat2eBRakAxFtt9",
      "product_id": "prod_5jnudVkLGZWF4AqMFBs5t5",
      "price_id": "pprice_4W0mJK6uGiQzHbVhfaFTl1",
      "units": 1,
      "created_at": "2025-01-26T11:20:40.296Z",
      "updated_at": "2025-01-26T11:20:40.296Z",
      "mode": "local"
    }
  ],
  "collection_method": "charge_automatically",
  "status": "active",
  "current_period_start_date": "2025-01-26T11:20:36.000Z",
  "current_period_end_date": "2025-02-26T11:20:36.000Z",
  "canceled_at": null,
  "created_at": "2025-01-26T11:20:40.292Z",
  "updated_at": "2025-01-26T11:22:16.388Z",
  "mode": "local"
}
}

subscription.trialing

A subscription started a trial period

Sample Request Body

{
"id": "evt_2ciAM8ABYtj0pVueeJPxUZ",
"eventType": "subscription.trialing",
"created_at": 1739963911073,
"object": {
  "id": "sub_dxiauR8zZOwULx5QM70wJ",
  "object": "subscription",
  "product": {
    "id": "prod_3kpf0ZdpcfsSCQ3kDiwg9m",
    "name": "trail",
    "description": "asdfasf",
    "image_url": null,
    "price": 1100,
    "currency": "EUR",
    "billing_type": "recurring",
    "billing_period": "every-month",
    "status": "active",
    "tax_mode": "exclusive",
    "tax_category": "saas",
    "default_success_url": "",
    "created_at": "2025-02-19T11:18:07.570Z",
    "updated_at": "2025-02-19T11:18:07.570Z",
    "mode": "test"
  },
  "customer": {
    "id": "cust_4fpU8kYkQmI1XKBwU2qeME",
    "object": "customer",
    "email": "customer@emaildomain",
    "name": "Alec Erasmus",
    "country": "NL",
    "created_at": "2024-11-07T23:21:11.763Z",
    "updated_at": "2024-11-07T23:21:11.763Z",
    "mode": "test"
  },
  "items": [
    {
      "object": "subscription_item",
      "id": "sitem_1xbHCmIM61DHGRBCFn0W1L",
      "product_id": "prod_3kpf0ZdpcfsSCQ3kDiwg9m",
      "price_id": "pprice_517h9CebmM3P079bGAXHnE",
      "units": 1,
      "created_at": "2025-02-19T11:18:30.690Z",
      "updated_at": "2025-02-19T11:18:30.690Z",
      "mode": "test"
    }
  ],
  "collection_method": "charge_automatically",
  "status": "trialing",
  "current_period_start_date": "2025-02-19T11:18:25.000Z",
  "current_period_end_date": "2025-02-26T11:18:25.000Z",
  "canceled_at": null,
  "created_at": "2025-02-19T11:18:30.674Z",
  "updated_at": "2025-02-19T11:18:30.674Z",
  "mode": "test"
  }
}

subscription.paused

A subscription was paused.

Sample Request Body

{
"id": "evt_5veN2cn5N9Grz8u7w3yJuL",
"eventType": "subscription.paused",
"created_at": 1754041946898,
"object": {
  "id": "sub_3ZT1iYMeDBpiUpRTqq4veE",
  "object": "subscription",
  "product": {
    "id": "prod_sYwbyE1tPbsqbLu6S0bsR",
    "object": "product",
    "name": "Prod",
    "description": "My Product Description",
    "price": 2000,
    "currency": "EUR",
    "billing_type": "recurring",
    "billing_period": "every-month",
    "status": "active",
    "tax_mode": "exclusive",
    "tax_category": "saas",
    "default_success_url": "",
    "created_at": "2025-08-01T09:51:26.277Z",
    "updated_at": "2025-08-01T09:51:26.277Z",
    "mode": "test"
  },
  "customer": {
    "id": "cust_4fpU8kYkQmI1XKBwU2qeME",
    "object": "customer",
    "email": "customer@emaildomain",
    "name": "Test Test",
    "country": "NL",
    "created_at": "2024-11-07T23:21:11.763Z",
    "updated_at": "2024-11-07T23:21:11.763Z",
    "mode": "test"
  },
  "items": [
    {
      "object": "subscription_item",
      "id": "sitem_1ZIqcUuxKKDTj5WZPNsN6C",
      "product_id": "prod_sYwbyE1tPbsqbLu6S0bsR",
      "price_id": "pprice_1uM3Pi1vJJ3xkhwQuZiM42",
      "units": 1,
      "created_at": "2025-08-01T09:51:50.497Z",
      "updated_at": "2025-08-01T09:51:50.497Z",
      "mode": "test"
    }
  ],
  "collection_method": "charge_automatically",
  "status": "paused",
  "current_period_start_date": "2025-08-01T09:51:47.000Z",
  "current_period_end_date": "2025-09-01T09:51:47.000Z",
  "canceled_at": null,
  "created_at": "2025-08-01T09:51:50.488Z",
  "updated_at": "2025-08-01T09:52:26.822Z",
  "mode": "test"
}
}

credits.granted

Credits were added to a customer’s credit account. It fires for every credit that raises a balance, for example a credit through the API or an auto-recharge top-up. Reversals don’t fire it. amount_minor_units and balance_after_minor_units are strings in the account’s units.

Sample Request Body

{
"id": "evt_4kR9vN2xQ7bT1mY8pW3cLd",
"eventType": "credits.granted",
"created_at": 1789430400123,
"object": {
  "id": "cct_3mNpK8rW2xY",
  "object": "customer_credits_grant",
  "customer_id": "cust_abc123",
  "account_id": "cca_7hQ2nL5vX9k",
  "bucket_name": "ai_credits",
  "unit_label": "credits",
  "amount_minor_units": "5000",
  "balance_after_minor_units": "5250",
  "reference": "order_789",
  "occurred_at": "2026-09-15T00:00:00.000Z"
}
}

credits.consumed

Credits were debited from a customer’s credit account, either through the API or by prepaid usage settlement. Reversals don’t fire it. Use balance_after_minor_units to warn a customer before their balance runs out.

Sample Request Body

{
"id": "evt_6pZ3cM8wK1rV5nB2tX9fQs",
"eventType": "credits.consumed",
"created_at": 1789430400456,
"object": {
  "id": "cct_9tBvR4mX1pQ",
  "object": "customer_credits_consumption",
  "customer_id": "cust_abc123",
  "account_id": "cca_7hQ2nL5vX9k",
  "bucket_name": "ai_credits",
  "unit_label": "credits",
  "amount_minor_units": "10",
  "balance_after_minor_units": "5240",
  "reference": "req_01J9X8K2",
  "occurred_at": "2026-09-15T00:00:00.000Z"
}
}

customer_credits.exhausted

A customer’s credits ran out while Creem settled a prepaid usage price on one of their products. It fires once per exhaustion: the first refused settlement sends it, and it fires again only after credits were added and ran out again. Creem also emails the customer. A debit through the API that exceeds the balance doesn’t fire this event. That request fails with 422 and the error code insufficient_balance. See Auto-refill for how exhaustion episodes and automatic top-ups work.

Sample Request Body

{
"id": "evt_1wT8kP4nR6vY2cM9bX5hLz",
"eventType": "customer_credits.exhausted",
"created_at": 1789430400789,
"object": {
  "id": "credits-exhausted:store_test:cust_test:default:none",
  "object": "customer_credits_exhaustion",
  "customer_id": "cust_test",
  "bucket_name": "default",
  "unit_label": "credits",
  "shortfall_minor_units": "250",
  "occurred_at": "2026-09-15T00:00:00.000Z"
}
}

credits.auto_recharged

An empty credit account was topped up with an automatic charge. It fires only for customers who opted in to auto-recharge, after the charge succeeds and the credits are added. The same top-up also fires credits.granted. See Auto-refill for consent, guardrails, and how the charge is made.

Sample Request Body

{
"id": "evt_8nQ5xL2vB7mR3kT9cW1pYd",
"eventType": "credits.auto_recharged",
"created_at": 1789430401012,
"object": {
  "id": "cct_5kLm2Qx8vRt",
  "object": "customer_credits_auto_recharge",
  "customer_id": "cust_test",
  "bucket_name": "default",
  "unit_label": "credits",
  "amount_minor_units": "2000",
  "currency": "EUR",
  "charge_reference": "pay_test_charge",
  "reference": "usage-window:mtr_test:cust_test:2026-01-01:default"
}
}

Get Started

AI

Features

Code

Integrations

Community

Merchant of Record

For Customers

What is a webhook?

Steps to receive a webhook

1. Create a local endpoint to receive requests

2. Register your development webhook endpoint

3. Test that your webhook endpoint is working properly

4. Deploy your webhook endpoint

5. Register your production webhook endpoint

Register endpoints programmatically

Network Configuration

Webhook Signatures

How to verify Creem signature?

Event Types

checkout.completed

License keys

subscription.active

subscription.paid

subscription.canceled

subscription.scheduled_cancel

subscription.past_due

subscription.unpaid

subscription.expired

refund.created

dispute.created

subscription.update

subscription.trialing

subscription.paused

credits.granted

credits.consumed

customer_credits.exhausted

credits.auto_recharged

​What is a webhook?

​Steps to receive a webhook

​1. Create a local endpoint to receive requests

​2. Register your development webhook endpoint

​3. Test that your webhook endpoint is working properly

​4. Deploy your webhook endpoint

​5. Register your production webhook endpoint

​Register endpoints programmatically

​Network Configuration

​Webhook Signatures

​How to verify Creem signature?

​Event Types

​checkout.completed

​License keys

​subscription.active

​subscription.paid

​subscription.canceled

​subscription.scheduled_cancel

​subscription.past_due

​subscription.unpaid

​subscription.expired

​refund.created

​dispute.created

​subscription.update

​subscription.trialing

​subscription.paused

​credits.granted

​credits.consumed

​customer_credits.exhausted

​credits.auto_recharged

What is a webhook?

Steps to receive a webhook

1. Create a local endpoint to receive requests

2. Register your development webhook endpoint

3. Test that your webhook endpoint is working properly

4. Deploy your webhook endpoint

5. Register your production webhook endpoint

Register endpoints programmatically

Network Configuration

Webhook Signatures

How to verify Creem signature?

Event Types

checkout.completed

License keys

subscription.active

subscription.paid

subscription.canceled

subscription.scheduled_cancel

subscription.past_due

subscription.unpaid

subscription.expired

refund.created

dispute.created

subscription.update

subscription.trialing

subscription.paused

credits.granted

credits.consumed

customer_credits.exhausted

credits.auto_recharged