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.

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 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

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.

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
`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

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)

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

Payload format

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

{
  "id": "whev_abc123",
  "created_at": "2026-06-21T10:30:00Z",
  "type": "order.paid",
  "api_version": "v1",
  "data": {
    "id": "ord_xyz789",
    "object": "order",
    "email": "john@example.com",
    "created_at": "2026-06-21T10:29:55Z"
  }
}

Field	Description
`id`	Unique id for this event (`whev_…`) — use it to deduplicate
`created_at`	ISO 8601 timestamp the event was created
`type`	The event type (e.g. `order.paid`)
`api_version`	API version used to render the payload
`data`	The serialized resource for the event (order, customer, invoice, …)

The shape of data varies by event type — it’s the serialized resource relevant to that event.

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
}

Fetch a single delivery with GET /webhook_events/{id}.

Retry behavior

Crevio expects a 2xx response within 5 seconds. If the request fails or times out:

The event is marked failed.
Failed events are retained for 7 days, then auto-deleted.
Crevio does not auto-retry failed deliveries. Re-trigger the underlying action, or use the test feature.

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.

Security

Verifying signatures

Every request includes an X-Crevio-Hmac-SHA256 header: a Base64-encoded HMAC-SHA256 of the raw request body, keyed with your signing secret. Verify it before trusting a payload.

Read the raw body

Read the request body as a raw string — do not re-serialize parsed JSON.

Compute the digest

HMAC-SHA256 over the raw body, keyed with your whsec_ secret.

Base64-encode

Base64-encode the digest.

Compare

Constant-time compare against the header value.

import crypto from "crypto";

function verifyWebhook(rawBody, signature, secret) {
  const computed = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("base64");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

import hmac, hashlib, base64

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    computed = base64.b64encode(
        hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(computed, signature)

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

Available events

Commerce

Leads & customers

Catalog

AI Tasks & Jobs

Email

Payload format

Delivery history

Retry behavior

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

​Available events

​Commerce

​Leads & customers

​Catalog

​AI Tasks & Jobs

​Email

​Payload format

​Delivery history

​Retry behavior

​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

Available events

Commerce

Leads & customers

Catalog

AI Tasks & Jobs

Email

Payload format

Delivery history

Retry behavior

Endpoint statuses

Security

Verifying signatures

Best practices

Output formats

How webhooks differ from event-triggered Tasks

Next steps