Webhooks

​

Subscribe

[[webhooks]]
topics = ["orders/created", "orders/delivered", "app/uninstalled"]
uri    = "/webhooks"

​

Topics

• app/*, business/redact and bulk/finished reach only the installation they are about, never another app. Every other topic reaches each active installation of the business that subscribes to it and was granted its scope.
• An installation limited to selected stores receives order, checkout, product and stock events of its stores only. Customer events carry that installation’s stores’ counters.
• The resources (order, product, …) are the same as the Admin API’s (Orders, Products and collections, Stock, Customers), masked the same way.

​

What you receive

POST /webhooks HTTP/1.1
content-type: application/json
user-agent: Tassyir-Webhooks/1.0 (+https://developers.tassyir.io)
webhook-id: dlv_741939488313319175
webhook-timestamp: 1760173964
webhook-signature: v1a,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4…
tassyir-topic: orders/delivered
tassyir-business-id: 632000000000000001
tassyir-api-version: 2026-10

{
  "id": "evt_741000000000000001",
  "type": "orders/delivered",
  "apiVersion": "2026-10",
  "createdAt": "2026-10-11T09:12:44.120Z",
  "businessId": "632000000000000001",
  "storeId": "632000000000000100",
  "appId": "741000000000000900",
  "installationId": "755000000000000001",
  "changed": ["delivered", "deliveredAt"],
  "data": { "order": { "id": "741000000000000500", "orderNumber": "1042" } }
}

​

Verify every delivery

import { isTassyirError, TassyirVerificationError } from '@tassyir/app';

/** Where you keep installations and handled deliveries. */
export interface WebhookState {
  isInstallation(installationId: string): Promise<boolean>;
  hasHandled(webhookId: string): Promise<boolean>;
  /** Records a webhook-id, once its event is handled (or durably queued). */
  markHandled(webhookId: string): Promise<void>;
}

// POST /webhooks
export async function receive(
  request: Request,
  state: WebhookState,
): Promise<Response> {
  let delivery;
  try {
    delivery = await tassyir.verifyWebhook(request, {
      // A delivery can arrive before app/installed: refuse it, Tassyir retries.
      installationId: async (id, event) =>
        event.type === 'app/installed' || (await state.isInstallation(id)),
      testDeliveries: 'accept',
    });
  } catch (error) {
    if (isTassyirError(error, 'KEYS_UNAVAILABLE'))
      return new Response(null, { status: 503 });
    if (error instanceof TassyirVerificationError)
      return new Response(null, { status: 400 });
    throw error;
  }
  if (delivery.test) return new Response(null, { status: 200 });

  // At least once: a webhook-id you already handled is answered and skipped.
  if (await state.hasHandled(delivery.id)) {
    return new Response(null, { status: 200 });
  }

  switch (delivery.event.type) {
    case 'orders/delivered': {
      const { order } = delivery.event.data;
      console.log(
        `order ${order.orderNumber} delivered, ${order.total ?? '?'} ${order.currency}`,
      );
      break;
    }
    case 'app/uninstalled':
      await tassyir.tokens.forget(delivery.installationId);
      break;
  }
  // Only now: if handling threw, Tassyir retries, and the retry is handled.
  await state.markHandled(delivery.id);
  return new Response(null, { status: 200 });
}

1. the v1a signature, against the keys of GET https://api.tassyir.io/apps/webhook-keys (cached an hour, fetched again when no key verifies). During a key rotation a delivery carries several signatures; any one that verifies is enough;
2. the timestamp, within 5 minutes of now;
3. the envelope’s appId (your numeric app id, TASSYIR_APP_ID: not the app_… client id) and installationId (your check);
4. the unsigned tassyir-* headers agree with the signed envelope.

​

Answer within 10 seconds

• Answer 2xx as soon as the delivery is verified and recorded; do slow work afterwards, from a queue. Tassyir does not read your answer’s body.
• Tassyir waits 10 seconds for the connection and your answer’s headers, and follows no redirect: a 3xx is a failed attempt.
• Your endpoint must be https on port 443, at a public hostname.

​

Retries, and disabled endpoints

• Three days of continuous failure disables the installation’s webhooks, and Tassyir emails you, at most once a day per app. Any 2xx resets the clock.
• Disabling is per installation, for all its topics. Until you re-enable it in the developer console, its events are recorded as skipped and never sent. Fix your endpoint first: a 410 or three more days of failure disables it again. Then replay the skipped deliveries that matter.
• A delivery still pending four days after its event fails.

​

Handle each event once

• Deduplicate on webhook-id: it is the same on every retry and replay of a delivery. Keep the ids for at least a week (replays are possible for 7 days).
• Record a webhook-id only once its event is handled, or saved to a durable queue that will handle it. An id recorded before a failed attempt makes the retry look handled, and the event is lost. Two copies of one delivery can still race: make what an event does safe to do twice.
• Never rely on order: compare the resource’s updatedAt with what you hold, and read it again when unsure.
• An event for an installation you do not know yet (it overtook app/installed) can be refused with a 4xx: it is retried.

​

How events are recorded

• One fact, one event. Confirming, cancelling, dispatching, delivering or returning an order sends that topic. orders/updated is sent for every other change an app can read (the buyer, the items, the delivery and the carrier’s status, scheduling, archiving, a waiting order unlocking), with changed naming the order’s top-level fields. A write that also changed fields outside its topic’s own sends orders/updated for those too.
• orders/created is sent once per real order. An abandoned checkout is abandoned_checkouts/created; when it becomes an order (same id), orders/created is sent then.
• A returned order keeps its status (usually pending): read the returned flag.
• Carriers. A carrier’s status change is orders/updated with changed naming delivery (and status when the order’s status moved with it). A carrier update that changes nothing sends nothing.
• Products. products/updated names the product’s top-level fields that changed (price, variants, images, active, collectionIds, …). A deactivated product is products/updated with active: false: no product is ever deleted, so products/deleted is not sent today.
• Stock. inventory_levels/updated is sent once per stock item per change, with changed empty: the body is the item’s whole stock. Stock can be negative after a dispatch shortfall; it is sent as it is.
• Customers. customers/updated is sent when a customer reads differently, never when it was only recomputed.

​

Test, replay and read the log

• Send a test (the Installs tab): a synthetic event of one topic your installation subscribes to, with sample data (order TEST-1001, buyer “Test Buyer”), signed and sent like a real delivery. It is marked by the header tassyir-test: true, a webhook-id of dlv_test_… and the envelope id evt_0; its businessId, appId and installationId are real. It is never retried, never logged, and never disables your endpoint. @tassyir/app refuses test deliveries (WEBHOOK_TEST_DELIVERY) unless you pass testDeliveries: 'accept'; then delivery.test is true.
• Read the log (the Webhook deliveries tab): every delivery of the last 30 days, metadata only (status, HTTP status, error, duration, attempts), never a body.
• Replay a delivery: one more attempt now, with the same webhook-id and a body rebuilt from the resource as it is now. A failed replay is final (no retry follows). A delivery can be replayed while its event is kept, 7 days.