Webhooks

Webhooks push events to your server the moment they happen — no polling. You register an HTTPS endpoint, choose which events to receive, and Crevio sends a signed JSON POST whenever one fires. Use them to sync data, trigger your own automations, fulfill purchases, and feed analytics — anything where your code needs to react to something happening in Crevio.

Webhooks notify your server so your code acts. If you instead want Crevio’s AI to act on an event, use an event-triggered Task. See How webhooks differ from event-triggered Tasks.

Creating an endpoint

Create endpoints from the dashboard, via the API, or with the TypeScript SDK.

Via dashboard

Open Developer settings

In your dashboard, go to Settings → Developer.

Create a new endpoint

Click New webhook endpoint and enter the HTTPS URL that should receive events. (HTTP is allowed only in local development.)

Select events

Choose which event types to subscribe to, individually or all at once.

Save and copy the secret

Crevio generates a signing secret (prefixed whsec_) shown once. Copy it now — you’ll use it to verify incoming requests.

Via API

Like every Crevio endpoint, params go at the top level (no {"webhook_endpoint": {...}} wrapper). Subscribe with enabled_events.

cURL
SDK (TypeScript)

curl -X POST https://api.crevio.co/v1/webhook_endpoints \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/crevio",
    "status": "active",
    "enabled_events": ["order.paid", "checkout.created"]
  }'

import { Crevio } from "@crevio/sdk";

const crevio = new Crevio({ apiKeyAuth: "YOUR_API_TOKEN" });

const endpoint = await crevio.webhookEndpoints.create({
  url: "https://example.com/webhooks/crevio",
  status: "active",
  enabledEvents: ["order.paid", "checkout.created"],
});

The response includes a secret — returned only on creation:

{
  "id": "wh_abc123",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/crevio",
  "api_version": "v1",
  "status": "active",
  "enabled_events": ["order.paid", "checkout.created"],
  "secret": "whsec_...",
  "created_at": "2026-06-21T10:30:00Z",
  "updated_at": "2026-06-21T10:30:00Z"
}

Copy your signing secret immediately. It’s shown once on creation and cannot be retrieved later — you’ll need it to verify signatures.

The url can point at a Crevio site that only signed-in visitors can open, on any path. Crevio’s deliveries to your own account’s sites pass its sign-in check, while anyone else is still asked to sign in. Verify the signature in your handler all the same, as you would on a public site. List the available event types programmatically:

curl https://api.crevio.co/v1/webhook_endpoints/events \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Testing an endpoint

Send a synthetic event to any active endpoint to verify your handler:

curl -X POST "https://api.crevio.co/v1/webhook_endpoints/wh_abc123/test?event_type=order.paid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

event_type must be one the endpoint is subscribed to. A test delivery is signed like a real one, but it carries "test": true, "livemode": false and an empty data.object — acknowledge it as soon as the signature checks out, or your own validation will fail a test that was never going to carry an order. The response is what your server answered, so a handler that rejects the event tells you why:

{
  "delivered": false,
  "response_code": 401,
  "response_body": "{\"error\":\"invalid signature\"}",
  "message": "HTTP 401: Unauthorized"
}

// verify first, then:
if (event.test) return new Response(null, { status: 204 });

delivered is true for any 2xx. If nothing answers at all — DNS failure, refused connection, timeout — the call returns 502 instead. The test event is signed like a real one, so it exercises your signature check. You can also test from the dashboard: Settings → Developer → Send test, then pick an event type. Test deliveries include "test": true in the body and are not persisted to your delivery history.

Use webhook.site or ngrok during development to inspect payloads without standing up a server.

Testing a paid order end to end

A test event proves your endpoint is reachable and your secret is right. To run your real fulfillment code on a real order without charging a card, make a test purchase:

Create the checkout the way your site does

POST /v1/checkouts with your line items and metadata, exactly as in production. See Checkouts.

Complete it as a test purchase

POST /v1/checkouts/{id}/test_purchase with a key or OAuth token of an account admin. Or open its purchase_url in a browser signed in to Crevio as an admin of the store: the card form is replaced by a Test purchase notice.

Watch your endpoint

No card is charged and Stripe is not called. Crevio creates the order and sends order.created and order.paid to your endpoint, plus subscription.created when the checkout starts a subscription.

Each checkout can be completed once, so create a new one for every run. An account can place 5 test purchases a minute. These are ordinary events, not test events: they have no test flag, they are signed and retried like any other, and data.object is the full order. The checkout’s metadata is copied onto the order, so the key your site saved before checkout comes back in the event. What marks the order as a test is livemode. It is on the event itself and on the order:

{
  "type": "order.paid",
  "livemode": false,
  "data": {
    "object": {
      "id": "ord_xyz789",
      "object": "order",
      "livemode": false,
      "status": "succeeded",
      "metadata": { "order_number": "CC-1042" }
    }
  }
}

Branch on the event’s livemode wherever your handler acts on the outside world. Every event has it, including events whose data.object has no livemode of its own, so one check covers all of them:

if (!event.livemode) {
  // send the confirmation and the kitchen ticket to yourself only, and skip fulfillment
}

The order’s customer is the signed-in owner who made the test purchase, not the email or customer on the checkout, so Crevio’s own receipt goes to you. A test order uses up no stock and doesn’t count toward sales. Its amount is what the checkout would have charged, and charge is null. The rest of the order’s life works without Stripe too, and every event it sends has livemode: false:

You do	Your endpoint gets
Refund the test order from the dashboard or `POST /v1/refunds`	`refund.created`, then `refund.updated` once the order is `refunded` or `partially_refunded`. The refund’s id starts with `re_test_`
Wait for a test subscription’s period to end	`order.created` and `order.paid` for the renewal order, then `subscription.renewed`
Cancel the test subscription and wait for its period to end	`subscription.ended`

Test subscriptions renew and end on an hourly check, so subscription.renewed and subscription.ended can arrive up to an hour after the period closes. A test renewal sends no renewal receipt, because nothing was charged. GET /v1/refunds and GET /v1/refunds/{id} return test refunds too, with livemode: false.

The event goes to the URL registered on your endpoint, nowhere else. If your site has a preview copy with its own database, an order saved there will not be found by the live site when the event arrives. Test from the site your endpoint points to.

There is no Stripe test mode for checkouts, so test card numbers like 4242 4242 4242 4242 are declined. A test purchase covers everything except the card charge itself.

Available events

These are the event types you can subscribe to via enabled_events. Each has a dedicated page under Webhook Events in the API reference showing its exact payload.

Commerce

Event	Fires when
`checkout.created`	A checkout session is created
`order.created`	An order is created
`order.paid`	An order is paid
`order.disputed`	The buyer disputes the payment with their bank (a chargeback or an early inquiry)
`order.dispute_closed`	A dispute is closed, won or lost
`refund.created`	A refund is issued
`refund.updated`	A refund’s status changes
`invoice.created`	An invoice is created
`invoice.paid`	An invoice is paid
`invoice.past_due`	An invoice passes its due date
`invoice.voided`	An invoice is voided
`subscription.created`	A customer completes checkout for a subscription
`subscription.renewed`	A recurring payment succeeds
`subscription.canceled`	A subscription is set to end when its current period closes
`subscription.paused`	Payment collection is paused
`subscription.resumed`	A paused or canceled subscription is resumed
`subscription.past_due`	A renewal payment fails and retries begin
`subscription.ended`	A subscription has ended and access is revoked

subscription.canceled means the customer keeps access until ends_at. A subscription that is canceled immediately skips it and sends only subscription.ended. These events fire however the change was made — the API, the customer’s billing portal, or Stripe.

Subscription renewals

Every paid renewal of a subscription or payment plan is recorded as a new order. Each one sends order.created and order.paid, then subscription.renewed. Tell a renewal apart from a purchase by the order’s billing_reason, named as Stripe names the invoice:

`billing_reason`	The order is
`subscription_create`	The purchase that started the subscription
`subscription_cycle`	A paid renewal
`null`	A one-time purchase

Both subscription values come with subscription, the id of the subscription (sub_…) the order started or renewed. A renewal order has the purchase’s line_items and customer, its own charge and amount, checkout: null, and empty metadata: the metadata you set on the checkout stays on the purchase order, so your own order numbers are never reused. A handler that fulfils purchases on order.paid should branch on it, or every renewal will look like a new sale:

if (event.type === "order.paid") {
  const order = event.data.object
  if (order.billing_reason === "subscription_cycle") {
    // record the payment against order.subscription; don't ship or grant again
  } else {
    // fulfil the purchase
  }
}

A renewal paid in full by a discount charges nothing and creates no order, but still sends subscription.renewed. A subscription that starts with a free trial has no payment to tie it to an order, so its order is null. customer is always present.

Leads & customers

Event	Fires when
`lead.created`	A new lead is captured
`form_submission.created`	A form submission is received
`form_submission.confirmed`	A pending submission is confirmed (double opt-in)
`customer.confirmed`	A customer confirms their email (double opt-in)
`customer.tag_added`	A tag is added to a customer
`customer.tag_removed`	A tag is removed from a customer

Filter on data.tag.id to react to one specific tag. Bulk CSV imports and deleting a tag outright do not send per-customer tag events.

Catalog

Event	Fires when
`product.created`	A product is created
`product.updated`	A product is updated

AI Tasks & Jobs

Event	Fires when
`task.created`	An AI task is created
`task_run.completed`	A task run finishes successfully
`task_run.failed`	A task run fails
`task_run.needs_input`	A supervised task run is awaiting input
`job.completed`	A background job (e.g. media generation) completes
`job.failed`	A background job fails

Email

Event	Fires when
`email_message.received`	An inbound email is received
`email_message.sent`	An email is sent
`email_message.delivered`	An email is delivered
`email_message.bounced`	An email bounces
`email_message.complained`	A recipient marks an email as spam
`email_message.failed`	An email fails to send

Event	Fires when
`x.mention.received`	New posts mention your connected X account. Polled every five minutes, and only while the account has an active task triggered by this event — see Mentions of your X account

Payload format

Every delivery is an HTTP POST with a JSON body in this shape:

{
  "id": "whev_abc123",
  "object": "event",
  "created_at": "2026-06-21T10:30:00Z",
  "type": "order.paid",
  "livemode": true,
  "api_version": "v1",
  "data": {
    "object": {
      "id": "ord_xyz789",
      "object": "order",
      "livemode": true,
      "status": "succeeded",
      "amount": 4900,
      "currency": "usd",
      "customer": { "id": "cus_abc123", "object": "customer", "email": "john@example.com" },
      "created_at": "2026-06-21T10:29:55Z"
    }
  }
}

Field	Description
`id`	Unique id for this event (`whev_…`) — use it to deduplicate
`object`	Always `event`
`created_at`	ISO 8601 timestamp the event was created
`type`	The event type (e.g. `order.paid`)
`livemode`	`false` when a test purchase or a dashboard test event caused the event, `true` otherwise
`api_version`	The payload version this endpoint is pinned to — see Versioning
`data.object`	The resource the event is about

data.object is the resource exactly as the API returns it — an order.paid event carries the same object as GET /v1/orders/{id}, so one parser handles both. References are ids you can fetch (checkout, order), and the ones you almost always need arrive already expanded: customer on checkout, order, refund, invoice and subscription events, plus line_items on orders and order.line_items on subscriptions. Refund events carry the refunded order as data.object — its amount_refunded and status reflect the refund. Dispute events carry the disputed order. On order.disputed its status is disputed. On order.dispute_closed the status tells you the outcome: back to succeeded (or partially_refunded) when the dispute was won or the inquiry closed, still disputed when it was lost. A lost dispute also removes the buyer’s access, as a full refund does, except on a renewal order: access there comes from the subscription, which keeps running. Tag events carry the customer as data.object and the tag that was added or removed as data.tag.

Delivery history

Each delivered event is persisted as a webhook event you can inspect. List your delivery history:

curl https://api.crevio.co/v1/webhook_events \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "object": "list",
  "data": [
    {
      "id": "whev_abc123",
      "object": "webhook_event",
      "type": "order.paid",
      "created_at": "2026-06-21T10:30:00Z"
    }
  ],
  "has_more": false
}

Narrow the list to one endpoint with ?webhook_endpoint=wh_abc123, or by status and event_type. Fetch a single delivery with GET /webhook_events/{id}; add ?expand[]=request to see the response code, response body and attempt count.

Redelivering an event

Send a delivered or failed event again, unchanged:

curl -X POST https://api.crevio.co/v1/webhook_events/whev_abc123/redeliver \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The redelivery carries the same id and the same payload, so a handler that deduplicates on id treats it as the event it already saw. Events are kept for 7 days. The call returns 409 while the event is still being delivered, or when its endpoint is disabled.

Versioning

Every endpoint is pinned to a payload version — api_version on the endpoint, repeated in each event. A new endpoint is pinned to the current version, and that never changes for you: when a payload changes in a way that could break a parser, it ships as a new version, and existing endpoints keep receiving the one they were built against. Opt in when you are ready:

curl -X PATCH https://api.crevio.co/v1/webhook_endpoints/wh_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_version": "v1"}'

New fields and new event types are not breaking changes and reach every version, so write parsers that ignore what they don’t recognise. The current version is v1.

Retry behavior

Crevio expects a 2xx response within 5 seconds. Redirects are not followed. Anything else — a timeout, a 4xx, a 5xx — counts as a failure, and the event is retried on this schedule:

Attempt	Wait before it
2	30 seconds
3	2 minutes
4	8 minutes
5	30 minutes
6	1 hour
7	3 hours
8	6 hours
9–13	12 hours each

That is about three days in all. After the last attempt the event is marked failed; you can still redeliver it for 7 days. Delivery is at least once, and order is not guaranteed — a retry of an older event can land after a newer one. Deduplicate on id, and fetch the resource from the API when order matters.

When an endpoint keeps failing

After 24 hours in which every delivery failed, the account owner gets a warning email.
After 72 hours, the endpoint is switched to inactive and the owner is told. Events still waiting to retry are marked failed.

One successful delivery at any point resets both clocks. Once the receiving end is fixed, set the endpoint back to active and redeliver what it missed.

Endpoint statuses

Status	Meaning
`active`	Receiving events normally
`inactive`	Disabled — receives no events

Deactivate an endpoint without deleting it; reactivating resumes delivery for new events. Crevio sets inactive itself only after 72 hours of failures.

Security

Verifying signatures

Crevio signs deliveries to the Standard Webhooks specification, so you verify them with an existing library instead of writing HMAC code. Every request carries three headers:

Header	Value
`webhook-id`	The event’s id — the same on every retry, and the same as `id` in the body
`webhook-timestamp`	Unix seconds when this attempt was sent
`webhook-signature`	`v1,<signature>`

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.CREVIO_WEBHOOK_SECRET); // the whole whsec_… string

export async function POST(request) {
  const rawBody = await request.text(); // never request.json() — verification needs the exact bytes

  let event;
  try {
    event = webhook.verify(rawBody, Object.fromEntries(request.headers));
  } catch {
    return new Response("invalid signature", { status: 401 });
  }

  if (event.type === "order.paid") {
    const order = event.data.object;
    // …
  }
  return new Response(null, { status: 204 });
}

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["CREVIO_WEBHOOK_SECRET"])  # the whole whsec_… string

def handle(raw_body: bytes, headers: dict):
    event = webhook.verify(raw_body, headers)  # raises WebhookVerificationError
    ...

# gem "standardwebhooks"
webhook = StandardWebhooks::Webhook.new(ENV.fetch("CREVIO_WEBHOOK_SECRET"))

# Rails: raises StandardWebhooks::WebhookVerificationError on a bad signature
event = webhook.verify(request.raw_post, {
  "webhook-id" => request.headers["webhook-id"],
  "webhook-timestamp" => request.headers["webhook-timestamp"],
  "webhook-signature" => request.headers["webhook-signature"]
})

The libraries also reject a webhook-timestamp more than five minutes old, which is what stops a captured request being replayed.

Verifying without a library

The signature is the base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>. The key is the bytes your secret encodes: strip the whsec_ prefix and base64-decode the rest — do not use the secret’s text as the key. Compare in constant time against the part of webhook-signature after v1,, and reject a timestamp more than five minutes old.

Always verify the signature before processing a payload. Without it, anyone could forge events to your endpoint.

Best practices

Respond fast — return 200 immediately, then process asynchronously to avoid timeouts.
Deduplicate — use the event id (whev_…); the same event may arrive more than once.
Use HTTPS — required in production.
Protect your secret — store it in env vars or a secrets manager; never commit it.

Output formats

Beyond the default JSON, Crevio can format deliveries for chat platforms:

Format	Use case
Raw (default)	Standard JSON for your own server
Slack	Pre-formatted for Slack incoming webhooks
Discord	Pre-formatted for Discord webhook URLs

Select the format when creating or editing the endpoint.

How webhooks differ from event-triggered Tasks

Both react to platform events, but they do different jobs:

	Webhook	Event-triggered Task
Who acts	Your server / your code	Crevio’s AI agent
You provide	An HTTPS endpoint	A natural-language prompt
Best for	Syncing, custom fulfillment, analytics	Autonomous follow-ups, drafting, decisions
Setup	`POST /webhook_endpoints`	`POST /tasks` with `trigger_type: "event"`

The subscribable internal events (and any third-party triggers) are documented under Events.

Next steps

Events

Internal and third-party triggers for event Tasks.

Tasks

Let Crevio’s AI react to events on your behalf.

Autonomous outreach

A worked event-triggered Task on order.paid.

API overview

The full set of primitives.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Creating an endpoint

Via dashboard

Via API

Testing an endpoint

Testing a paid order end to end

Available events

Commerce

Subscription renewals

Leads & customers

Catalog

AI Tasks & Jobs

Email

Payload format

Delivery history

Redelivering an event

Versioning

Retry behavior

When an endpoint keeps failing

Endpoint statuses

Security

Verifying signatures

Best practices

Output formats

How webhooks differ from event-triggered Tasks

Next steps

Events

Tasks

Autonomous outreach

API overview

​Creating an endpoint

​Via dashboard

​Via API

​Testing an endpoint

​Testing a paid order end to end

​Available events

​Commerce

​Subscription renewals

​Leads & customers

​Catalog

​AI Tasks & Jobs

​Email

​Social

​Payload format

​Delivery history

​Redelivering an event

​Versioning

​Retry behavior

​When an endpoint keeps failing

​Endpoint statuses

​Security

​Verifying signatures

​Best practices

​Output formats

​How webhooks differ from event-triggered Tasks

​Next steps

Events

Tasks

Autonomous outreach

API overview

Creating an endpoint

Via dashboard

Via API

Testing an endpoint

Testing a paid order end to end

Available events

Commerce

Subscription renewals

Leads & customers

Catalog

AI Tasks & Jobs

Email

Social

Payload format

Delivery history

Redelivering an event

Versioning

Retry behavior

When an endpoint keeps failing

Endpoint statuses

Security

Verifying signatures

Best practices

Output formats

How webhooks differ from event-triggered Tasks

Next steps