Webhooks

Register HTTPS endpoints to receive email events (delivery and engagement events for emails sent through POST /v1/emails), order events (lifecycle events for orders), payment-request events (lifecycle events for pay-links), contact events (lifecycle + consent changes), message events (inbound WhatsApp messages), deal events (lifecycle events for deals), booking events (lifecycle events for bookings), event-attendance events, and form-submission events. Events are signed, retried, and deduplicable by event id.

Email events fire only for API-originated sends (sends made with an idempotency key via POST /v1/emails); engagement events additionally require the send to have opted into tracking. Order events fire for every order write source — API, in-app, and automations — not just API-created orders (never for historical import ingestion). Payment-request events fire for hosted pay-links from every mint source (API and in-app) — never for direct saved-card charges or internal dunning-recovery links. Contact, message, deal, booking, attendance, and form events fire for every intentional write source too — their quiet paths are documented per family below.

All management endpoints require authentication. Errors use the structured envelope {"error": {"code", "message"}}.

POST /api/v1/webhook-endpoints

Maximum 3 endpoints per workspace (409 endpoint_limit_reached). The cap is enforced safely under concurrency.

curl -X POST "https://app.otok.io/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/otok-events",
    "events": ["email.delivered", "email.bounced", "email.complained", "order.created", "order.paid"]
  }'

Response 201:

{
  "id": "c9b8a7d6-e5f4-0312-2130-4a5b6c7d8e9f",
  "url": "https://hooks.example.com/otok-events",
  "events": ["email.delivered", "email.bounced", "email.complained", "order.created", "order.paid"],
  "is_active": true,
  "secret": "whsec_XkQ2mP9rT5vW8yZ1aB4cD7eF0gH3jK6nL9qS2uV5xY8",
  "created_at": "2026-07-14T10:00:00.000Z"
}

The secret is returned only here, once. Store it securely — it cannot be retrieved again. There is no rotation endpoint: to rotate, register a new endpoint with the same URL, switch verification to the new secret, then delete the old endpoint.

GET /api/v1/webhook-endpoints

No parameters (max 3 rows, unpaginated).

Response 200:

{
  "data": [
    { "id": "c9b8a7d6-…", "url": "https://hooks.example.com/otok-email", "events": ["email.delivered", "email.bounced", "email.complained"], "is_active": true, "created_at": "2026-07-14T10:00:00.000Z" }
  ]
}

Secrets are never included.

DELETE /api/v1/webhook-endpoints/:id

Response 204, no body. Deliveries stop immediately; anything still queued for the deleted endpoint is dropped.

Event types

Email events

A click does not emit an implied email.opened event. If you need "opened" semantics, treat a send as opened when you've received either email.opened or email.clicked.

Order events

Five order lifecycle events. All are opt-in: they are delivered only to endpoints that list them explicitly in events — an endpoint registered without an events list receives none of them.

Order events fire for every order write source, not just API-created orders. They are never fired for historical import ingestion.

Payment-request events

Four payment-request (pay-link) lifecycle events, mirroring the request's status vocabulary. All are opt-in: they are delivered only to endpoints that list them explicitly in events — an endpoint registered without an events list receives none of them.

Hosted pay-links only: direct saved-card charges (charge_kind: "token") and internal dunning-recovery links never emit payment_request.* events — the event stream is exactly the payer-facing links.

Contact events

Four contact lifecycle + consent events. All are opt-in (delivered only to endpoints that list them explicitly in events).

Quiet by design: CSV imports and bulk contact edits emit nothing; contact merges are fully silent (a merge is not a deletion — the absorbed contact emits no contact.deleted); the creation-time consent seed does not emit contact.consent_changed (contact.created carries the initial state); same-state consent re-assertions, double-opt-in ceremony markers, and preference-center metadata updates do not emit.

Message events

One inbound-message event. Opt-in (delivered only to endpoints that list it explicitly in events).

Media rides as metadata only (mime_type, filename, bytes) — never presigned URLs, media URLs, or storage keys.

Deal events

Four deal lifecycle events. All are opt-in (delivered only to endpoints that list them explicitly in events). They fire for every write source — manual, API, automations, and Salesforce sync — data.source says which.

Booking events

Four booking lifecycle events. All are opt-in (delivered only to endpoints that list them explicitly in events).

booking.completed / booking.no_show deliberately do not exist as webhooks: those statuses are sweep-derived (a cron inferring the past, not a user action).

Event-attendance events

One event type for the whole family — filter on data.status instead of subscribing per status. Opt-in.

Form events

One event type for every submission surface — data.origin is the discriminator. Opt-in.

Registering an endpoint for a mix of the new families:

curl -X POST "https://app.otok.io/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/otok-crm",
    "events": ["contact.created", "contact.updated", "contact.consent_changed", "deal.won", "form.submitted"]
  }'

Delivery payload

Every delivery is an HTTP POST with the same JSON envelope; the shape of data depends on the event family:

Email event data

{
  "id": "b2c3d4e5-f607-1829-3a4b-5c6d7e8f9012",
  "type": "email.bounced",
  "created_at": "2026-07-14T10:05:32.000Z",
  "data": {
    "send_id": "f0e1d2c3-b4a5-9687-7869-5a4b3c2d1e0f",
    "idempotency_key": "order-88123-receipt",
    "to": "customer@example.com",
    "reason": "550 5.1.1 user unknown",
    "bounce_type": "hard",
    "metadata": { "order_id": "88123" }
  }
}

Optional email-event fields are omitted, never null.

Order event data

{
  "id": "a1b2c3d4-e5f6-0718-2930-4a5b6c7d8e9f",
  "type": "order.refunded",
  "created_at": "2026-07-15T09:30:00.000Z",
  "data": {
    "order_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "external_id": null,
    "number": "1042",
    "platform": "api",
    "store_connection_id": null,
    "financial_status": "partially_refunded",
    "fulfillment_status": "unfulfilled",
    "currency": "ILS",
    "total": 360,
    "subtotal": 340,
    "discount_total": 0,
    "shipping_total": 20,
    "tax_total": 0,
    "refunded_total": 50,
    "coupon_codes": ["SUMMER10"],
    "item_count": 3,
    "first_item_name": "Widget",
    "placed_at": "2026-07-14T10:00:00.000Z",
    "paid_at": "2026-07-14T10:00:00.000Z",
    "cancelled_at": null,
    "refunded_at": "2026-07-15T09:30:00.000Z",
    "created_at": "2026-07-14T10:00:00.000Z",
    "refund": {
      "amount": 50,
      "external_refund_id": "r-1",
      "reason": "damaged",
      "refunded_at": "2026-07-15T09:30:00.000Z"
    }
  }
}

All five order events carry the same data fields (a snapshot of the order at event time):

Unlike email events, order event data always carries the full field set — absent values are explicit nulls, not omitted keys.

Payment-request event data

{
  "id": "c3d4e5f6-0718-2930-4a5b-6c7d8e9f0a1b",
  "type": "payment_request.paid",
  "created_at": "2026-07-15T11:20:00.000Z",
  "data": {
    "payment_request_id": "0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0",
    "status": "paid",
    "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
    "deal_id": null,
    "provider": "sumit",
    "amount": 250,
    "currency": "ILS",
    "title": "Onboarding session",
    "vat_mode": "inclusive",
    "vat_rate": 18,
    "test_mode": false,
    "pay_url": "https://app.otok.io/pay/pr_k3J9…",
    "contact_payment_id": "7b6a5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d",
    "expires_at": "2026-07-18T09:00:00.000Z",
    "paid_at": "2026-07-15T11:20:00.000Z",
    "cancelled_at": null,
    "created_at": "2026-07-15T09:00:00.000Z"
  }
}

All four payment-request events carry the same data fields (a snapshot of the request at event time), following the order-event conventions — the full field set with explicit nulls:

Provider correlation references and internal row metadata are deliberately excluded from the payload — read GET /v1/payment-requests/:id when you need them.

Contact event data

contact.created / contact.updated share a compact core; contact.deleted and contact.consent_changed have their own shapes. Absent values are explicit nulls.

{
  "id": "f6071829-3a4b-5c6d-7e8f-901234567890",
  "type": "contact.updated",
  "created_at": "2026-07-16T10:15:00.000Z",
  "data": {
    "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
    "changed_fields": ["lifecycle_stage", "tags", "custom_fields.plan"],
    "contact": {
      "id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
      "phone": "+972505555555",
      "email": "jane@example.com",
      "name": "Jane Cohen",
      "first_name": "Jane",
      "last_name": "Cohen",
      "lifecycle_stage": "customer",
      "source": "form",
      "block_state": "none",
      "lead_score": 72
    },
    "source": "manual"
  }
}

Message event data

{
  "id": "d4e5f607-1829-3a4b-5c6d-7e8f90123456",
  "type": "message.received",
  "created_at": "2026-07-16T08:12:05.000Z",
  "data": {
    "message_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
    "conversation_id": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f8091a",
    "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
    "channel": "whatsapp_api",
    "type": "image",
    "text": "Here is the signed form",
    "media": {
      "mime_type": "image/jpeg",
      "filename": "signed-form.jpg",
      "bytes": 482113
    },
    "wa_message_id": "wamid.HBgMOTcyNTA1NTU1NTU1FQIAEhg=",
    "timestamp": "2026-07-16T08:12:03.000Z"
  }
}

Deal event data

All four deal events carry the same data fields (a snapshot of the deal at event time, full field set with explicit nulls):

{
  "id": "e5f60718-293a-4b5c-6d7e-8f9012345678",
  "type": "deal.stage_changed",
  "created_at": "2026-07-16T09:00:00.000Z",
  "data": {
    "deal_id": "3c4d5e6f-7081-92a3-b4c5-d6e7f8091a2b",
    "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
    "pipeline_id": "4d5e6f70-8192-a3b4-c5d6-e7f8091a2b3c",
    "pipeline_name": "Sales",
    "stage_id": "5e6f7081-92a3-b4c5-d6e7-f8091a2b3c4d",
    "stage_name": "Negotiation",
    "from_stage_id": "6f708192-a3b4-c5d6-e7f8-091a2b3c4d5e",
    "from_stage_name": "Qualified",
    "status": "open",
    "title": "Onboarding package",
    "amount": 3600,
    "currency": "ILS",
    "owner_user_id": "708192a3-b4c5-d6e7-f809-1a2b3c4d5e6f",
    "external_reference": "crm-9912",
    "source": "api",
    "expected_close_at": "2026-08-01T00:00:00.000Z",
    "closed_at": null,
    "lost_reason": null
  }
}

Booking event data

All four booking events carry the same data fields (full field set, explicit nulls). The booking module is deliberately multi-timezone, so both the host and invitee timezones ride the payload. There is deliberately no manage_url — that is a capability token and never leaves through a webhook body (mint links from your own systems instead).

Event-attendance event data

Form event data

Request headers

Verifying signatures

Each delivery is signed with your endpoint's whsec_… secret:

• The signed payload is the string "<t>" + "." + <raw request body> — the exact bytes received on the wire, not re-serialized JSON.
• v1 is the lowercase hex HMAC-SHA256 of that string, keyed with the entire secret string including the whsec_ prefix.
• t is the unix-seconds timestamp of this delivery attempt — retries carry fresh timestamps, so you can enforce a replay window.
• Exactly one v1 value is sent per request.

Complete Node.js example (Express):

const crypto = require("node:crypto");
const express = require("express");

const WEBHOOK_SECRET = process.env.OTOK_WEBHOOK_SECRET; // the full "whsec_..." string
const TOLERANCE_SECONDS = 300; // 5 minutes

const app = express();

// IMPORTANT: capture the raw body — verification must use the exact bytes.
app.post("/otok-email", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Otok-Signature") || "";
  const match = signature.match(/^t=(\d+),v1=([0-9a-f]{64})$/);
  if (!match) return res.status(400).send("bad signature header");

  const [, t, receivedSig] = match;

  // 1. Reject stale timestamps (replay window)
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(t));
  if (age > TOLERANCE_SECONDS) return res.status(400).send("stale timestamp");

  // 2. Recompute the HMAC over "<t>.<rawBody>" with the FULL whsec_ secret
  const expectedSig = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${t}.${req.body}`) // req.body is a Buffer of the raw bytes
    .digest("hex");

  // 3. Timing-safe comparison
  const a = Buffer.from(expectedSig, "hex");
  const b = Buffer.from(receivedSig, "hex");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));

  // 4. Dedup by event id — retries (and rare double-enqueues) reuse the same id
  if (alreadyProcessed(event.id)) return res.status(200).send("ok");
  markProcessed(event.id);

  handleEvent(event); // your logic — keep it fast; respond 2xx within 10 seconds

  res.status(200).send("ok");
});

Always deduplicate by event id (event.id / X-Otok-Event-Id): the same id is reused for every retry of a delivery, and rare recovery paths can enqueue a delivery twice. Each of your registered endpoints receives its own delivery of the same event id.

Retry and transport policy

Recommendations:

• Use an https:// receiver. Plain http:// URLs are accepted, but then the HMAC signature is your only integrity protection and payloads travel unencrypted.
• Return 2xx immediately after signature verification and dedup; do real work asynchronously.
• Persist processed event ids for at least the ~16-hour retry window.
• If you miss events past the retry window, reconcile by polling your own send records — exhausted deliveries are not replayed.