Webhooks & Automation

Webhooks deliver commerce events — a new order, a successful payment, a completed catalog sync — as they happen, in place of polling the API on a timer. An HTTPS endpoint is registered and subscribed to a set of events, and Galactic Core POSTs a signed envelope to it on every matching event. One endpoint runs through its whole life here: created, with its one-time secret captured; read for health; a delivery verified; tested when it succeeds and when it fails; auto-disabled after repeated failures; and finally handling order.paid end to end. All webhook management is secret-key only (sk), so these calls run on your server. A publishable key returns 403.

import { Tybrite } from '@tybrite-labs/sdk';

const server = new Tybrite({ apiKey: process.env.TYBRITE_SECRET_KEY });

1. Registering an endpoint

An endpoint points at your handler URL and lists the events it subscribes to, or ["*"] for all of them. The response includes a signing_secret returned exactly once and never retrievable again — a lost secret is recovered by deleting the endpoint and re-creating it.

const { webhook_endpoint } = await server.webhooks.createWebhookEndpoint({
  requestBody: {
    url: 'https://yourapp.com/webhooks/tybrite',
    events: ['order.created', 'order.paid', 'payment.succeeded'],
    description: 'Production ERP sync',
  },
});

// Persist webhook_endpoint.signing_secret now — you won't see it again.

Response

{
  "webhook_endpoint": {
    "id": "ca8e7b1e-86e4-46a3-a716-eab9e5ffc168",
    "store_id": "ef7b07d3-424b-4b03-b1d4-30a2d2073b61",
    "url": "https://yourapp.com/webhooks/tybrite",
    "events": ["order.created", "order.paid", "payment.succeeded"],
    "enabled": true,
    "metadata": {},
    "created_at": "2026-06-20T11:30:48.673+00:00",
    "updated_at": "2026-06-20T11:30:48.673+00:00",
    "signing_secret": "whsec_REDACTED_64_HEX_CHARACTERS_STORE_THIS_NOW"
  }
}

The create response is the only one that ever includes signing_secret; getWebhookEndpoint and listWebhookEndpoints omit it, and there is no way to read it back. The mirror also holds: create carries no health fields and no delivery_stats, which appear only on get and list (step 2).

2. Listing and inspecting endpoints and their health

listWebhookEndpoints returns every endpoint with its delivery-health fields: last_success_at, last_failure_at, consecutive_failures, disabled_reason, and disabled_at. A freshly created endpoint carries them all at their zero state, null or 0.

const { webhook_endpoints } = await server.webhooks.listWebhookEndpoints();

Response

{
  "webhook_endpoints": [
    {
      "id": "ca8e7b1e-86e4-46a3-a716-eab9e5ffc168",
      "store_id": "ef7b07d3-424b-4b03-b1d4-30a2d2073b61",
      "url": "https://yourapp.com/webhooks/tybrite",
      "events": ["order.created", "order.paid", "payment.succeeded"],
      "enabled": true,
      "metadata": {},
      "last_success_at": null,
      "last_failure_at": null,
      "consecutive_failures": 0,
      "disabled_reason": null,
      "disabled_at": null,
      "created_at": "2026-06-20T11:30:48.673+00:00",
      "updated_at": "2026-06-20T11:30:48.673+00:00"
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

getWebhookEndpoint returns the same health fields and adds aggregate delivery_stats for a single endpoint:

const { webhook_endpoint } = await server.webhooks.getWebhookEndpoint({
  id: 'ca8e7b1e-86e4-46a3-a716-eab9e5ffc168',
});

Response

{
  "webhook_endpoint": {
    "id": "ca8e7b1e-86e4-46a3-a716-eab9e5ffc168",
    "store_id": "ef7b07d3-424b-4b03-b1d4-30a2d2073b61",
    "url": "https://yourapp.com/webhooks/tybrite",
    "events": ["order.created", "order.paid", "payment.succeeded"],
    "enabled": true,
    "metadata": {},
    "last_success_at": null,
    "last_failure_at": null,
    "consecutive_failures": 0,
    "disabled_reason": null,
    "disabled_at": null,
    "created_at": "2026-06-20T11:30:48.673+00:00",
    "updated_at": "2026-06-20T11:30:48.673+00:00",
    "delivery_stats": { "total": 0, "successful": 0, "failed": 0 }
  }
}

The field map across the two:

Field	`createWebhookEndpoint`	`getWebhookEndpoint` / `listWebhookEndpoints`
`signing_secret`	yes (once)	no
`last_success_at`, `consecutive_failures`, `disabled_reason`, …	no	yes
`delivery_stats`	no	get only

3. Health degradation and auto-disable

Failed deliveries are retried automatically with exponential backoff. Each failure bumps consecutive_failures and stamps last_failure_at; a success resets the counter. If an endpoint fails 20 deliveries in a row, Galactic Core disables it — enabled flips to false, a disabled_reason is stamped, and disabled_at is set. From then on it receives nothing. A disabled endpoint reads back like this:

const { webhook_endpoint } = await server.webhooks.getWebhookEndpoint({
  id: 'ca8e7b1e-86e4-46a3-a716-eab9e5ffc168',
});

Response

{
  "webhook_endpoint": {
    "id": "ca8e7b1e-86e4-46a3-a716-eab9e5ffc168",
    "store_id": "ef7b07d3-424b-4b03-b1d4-30a2d2073b61",
    "url": "https://yourapp.com/webhooks/tybrite",
    "events": ["order.created", "order.paid", "payment.succeeded"],
    "enabled": false,
    "metadata": {},
    "last_success_at": "2026-06-18T08:12:00.000+00:00",
    "last_failure_at": "2026-06-20T11:45:10.220+00:00",
    "consecutive_failures": 20,
    "disabled_reason": "auto_disabled_after_20_consecutive_failures",
    "disabled_at": "2026-06-20T11:45:10.220+00:00",
    "created_at": "2026-06-20T11:30:48.673+00:00",
    "updated_at": "2026-06-20T11:45:10.220+00:00",
    "delivery_stats": { "total": 42, "successful": 22, "failed": 20 }
  }
}

Patching enabled: true re-enables a recovered handler, which also resets the failure counter and clears disabled_reason:

const { webhook_endpoint } = await server.webhooks.updateWebhookEndpoint({
  id: 'ca8e7b1e-86e4-46a3-a716-eab9e5ffc168',
  requestBody: { enabled: true },
});
// → webhook_endpoint.enabled === true, consecutive_failures === 0, disabled_reason === null

4. The event envelope

Every delivery is a POST of the same envelope. data.object holds the resource that triggered the event, and the top-level fields describe it:

type — the event type, such as order.created.
livemode — true for a live key, false for a test key. This is the field that keeps test events away from production systems.
api_version — the contract version (v1).
environment — production or sandbox.

An order.created envelope as it lands in a handler, taken from the event log:

{
  "id": "evt_1781955476025_lp1jafe",
  "type": "order.created",
  "api_version": "v1",
  "livemode": true,
  "created_at": "2026-06-20T11:37:56.025Z",
  "data": {
    "object": {
      "id": "e7d28e96-e9e0-45ce-be28-51812f63eb4b",
      "customer_id": "8c958f7c-918f-488a-a7cc-71497f677a53",
      "order_number": "ORD-1781955473455",
      "order_status": "pending",
      "payment_status": "paid",
      "total_amount": 603.99
    }
  }
}

When that order’s payment confirms, an order.paid envelope for the same order id follows, identical in shape and differing only in type:

{
  "id": "evt_1781955479610_z8k2mq1",
  "type": "order.paid",
  "api_version": "v1",
  "livemode": true,
  "created_at": "2026-06-20T11:38:00.610Z",
  "data": {
    "object": {
      "id": "e7d28e96-e9e0-45ce-be28-51812f63eb4b",
      "customer_id": "8c958f7c-918f-488a-a7cc-71497f677a53",
      "order_number": "ORD-1781955473455",
      "order_status": "pending",
      "payment_status": "paid",
      "total_amount": 603.99
    }
  }
}

5. Verifying the signature in your handler

Galactic Core signs every delivery and sends the signature in the X-Tybrite-Signature header as t=<timestamp>,v1=<hex hmac>. A handler recomputes the HMAC over `${t}.${rawBody}` with its stored signing_secret and compares in constant time before trusting the payload. The example below is handler code, so it names its own stack:

// Your webhook handler (Express example) — verify before you act.
import { createHmac, timingSafeEqual } from 'crypto';
import express from 'express';

const app = express();
const SIGNING_SECRET = process.env.TYBRITE_WEBHOOK_SECRET; // the value from step 1

// Capture the RAW body — you must sign the exact bytes, not a re-serialized object.
app.post('/webhooks/tybrite', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Tybrite-Signature') || '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const rawBody = req.body.toString('utf8');

  const expected = createHmac('sha256', SIGNING_SECRET)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const ok =
    parts.v1 &&
    expected.length === parts.v1.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));

  if (!ok) return res.status(400).send('invalid signature');

  const event = JSON.parse(rawBody);
  // event.type, event.data.object — now safe to act on.
  res.status(200).json({ received: true });
});

A handler that answers 200 immediately and processes asynchronously stays healthy under load. A slow one causes timeouts, which count as delivery failures and move the endpoint toward auto-disable (step 3).

6. Testing, auditing, and retrying deliveries

A test event exercises connectivity and the signature check end to end. Its payload carries test: true and placeholder data, so a handler treats it as a no-op rather than fulfilling or charging against it. The response reports the status_code the endpoint returned. A handler answering 200 makes the test succeed:

const test = await server.webhooks.sendTestWebhookEvent({
  id: 'ca8e7b1e-86e4-46a3-a716-eab9e5ffc168',
  requestBody: { event_type: 'order.created' },
});

Response

{
  "success": true,
  "event_id": "evt_test_1781955051835_uuib0s8",
  "event_type": "order.created",
  "endpoint_url": "https://yourapp.com/webhooks/tybrite",
  "status_code": 200,
  "response_body": "{\"received\":true,\"event_id\":\"evt_test_1781955051835_uuib0s8\"}"
}

An endpoint that is down or rejects the request returns the same call with success: false and the failing status_code. A run of these is what trips the auto-disable in step 3:

Response

{
  "success": false,
  "event_id": "evt_test_1781955052910_h3p9wxa",
  "event_type": "order.created",
  "endpoint_url": "https://yourapp.com/webhooks/tybrite",
  "status_code": 500,
  "response_body": "Internal Server Error"
}

The event log is where deliveries are debugged and history replayed from. It is reverse-chronological, cursor-paged, and filterable by type and environment:

const { webhook_events } = await server.webhooks.listWebhookEvents({ limit: 10, type: 'order.paid' });

Response

{
  "webhook_events": [
    {
      "id": "evt_1781955476025_lp1jafe",
      "type": "order.created",
      "payload": {
        "id": "evt_1781955476025_lp1jafe",
        "type": "order.created",
        "api_version": "v1",
        "livemode": true,
        "created_at": "2026-06-20T11:37:56.025Z",
        "data": {
          "object": {
            "id": "e7d28e96-e9e0-45ce-be28-51812f63eb4b",
            "customer_id": "8c958f7c-918f-488a-a7cc-71497f677a53",
            "order_number": "ORD-1781955473455",
            "order_status": "pending",
            "payment_status": "paid",
            "total_amount": 603.99
          }
        }
      },
      "environment": "production",
      "created_at": "2026-06-20T11:37:56.025+00:00"
    }
  ],
  "pagination": { "limit": 10, "next_cursor": "MjAyNi0wNi0yMFQxMTozNzo1Mi4wMjYrMDA6MDA=", "has_more": true }
}

environment: 'sandbox' narrows the log to test-key events and 'production' to live ones — the same distinction the livemode flag carries on each envelope.

A manual re-delivery sends an event to every enabled, subscribed endpoint, logging each retry as a new attempt. retried counts the endpoints hit, and results[] reports each one’s outcome:

const retry = await server.webhooks.retryWebhookEvent({ id: 'evt_1781955476025_lp1jafe' });

Response

{
  "event_id": "evt_1781955476025_lp1jafe",
  "retried": 2,
  "results": [
    { "endpoint_id": "2b755d69-7627-40b3-b0b6-4458e23d64bc", "success": true, "status_code": 200 },
    { "endpoint_id": "58da9a58-6ac3-49ce-9150-0350519141b1", "success": true, "status_code": 200 }
  ]
}

7. Handling `order.paid` end to end

The order is not patched to paid from the webhook. When a payment confirms, Galactic Core has already marked the order paid, reduced stock, booked the sale, and updated the customer’s metrics. order.paid fires so that other systems can react to that — pushing the order into an ERP, sending a custom confirmation email, updating an analytics warehouse, notifying a fulfilment partner.

// Inside your verified handler (after the signature check in step 5):
const event = JSON.parse(rawBody);

if (event.type === 'order.paid' && event.livemode) {
  const order = event.data.object;
  await pushToErp(order);              // your system of record
  await sendConfirmationEmail(order);  // your email provider
  await trackRevenue(order);           // your analytics
}
// Do NOT re-mark the order paid — Galactic Core already did, including stock + accounting.

Supported event types

An endpoint subscribes to any of these, or to ["*"] for everything:

Order lifecycle — order.created, order.paid, order.fulfilled, order.shipped, order.cancelled, order.refunded, order.updated
Payment — payment.succeeded, payment.failed, payment.refunded
Customer — customer.created, customer.updated, customer.deleted
Inventory & catalog — product.created, product.updated, product.stock_low, product.out_of_stock
Cart & checkout — cart.created, cart.updated, cart.abandoned
Gift cards — gift_card.issued, gift_card.redeemed, gift_card.expired
Promotions — promotion.applied, promotion.created, promotion.activated (a promotion went live or was scheduled to), promotion.deactivated (a live promotion ended, was paused, or expired). A promotion awaiting approval is not yet a promotion: nothing fires while it is a draft, and promotion.created arrives when it is approved
Pricing — pricing_rule.created, pricing_rule.activated (a dynamic-pricing rule went live), pricing_rule.updated (a live rule’s discount, scope, priority, or window changed, so the prices it produces are now different), pricing_rule.deactivated. As with promotions, a rule awaiting approval emits nothing until it goes live
Content & collections — collection.created, collection.updated (name / banner / homepage placement changed, or membership changed — products added, removed, or re-ordered, carrying members_changed: true), post.published, lookbook.published, review.approved
Deletion & restore — product.deleted, product_variant.deleted, promotion.deleted, collection.deleted, post.deleted, lookbook.deleted, pricing_rule.deleted, subcategory.deleted, customer.deleted. The record has left the API: it is gone from every list, cannot be fetched by id, and stops taking effect — which makes each of these the moment anything built from that record, a page, a menu entry, a mirrored row, no longer has a source. Deleting is reversible for 90 days, so each event has a matching .restored and the payload carries restorable_until, leaving room either to remove a copy now and rebuild it if the restore arrives, or to wait the window out. Deleting a product also deletes its variants, so product.deleted is followed by a product_variant.deleted for each
Visibility — category.activated / category.deactivated, subcategory.activated / subcategory.deactivated. A category switched off is filtered out of every catalog read, so it leaves a storefront exactly as a deleted one would. Categories cannot be deleted — they are a fixed set a merchant enables or disables — so these are the only lifecycle events they emit, and the only signal available to navigation or any layout built from the taxonomy
Store lifecycle & configuration — store.updated (name / logo / branding / contact / base currency; carries changed_fields), payment_provider.connected, shipping_provider.connected, channel.connected
Feature availability — feature.status_changed (a capability crossed between available, awaiting_data, and not_in_plan; carries feature, status, previous_status)
Catalog sync & syndication — feed.sync.completed (a scheduled inbound feed-pull finished — carries created/updated/failed counts), channel.sync.completed (a sales-channel push finished — carries pushed/rejected counts)
Wholesale (B2B) — b2b.rfq.created, b2b.quote.sent / .accepted / .rejected, b2b.po.issued / .confirmed / .fulfilled, b2b.invoice.issued / .paid / .overdue (for stores with wholesale enabled)

Keeping a storefront in step with the store

The order, payment, and inventory events above track a transaction. The store lifecycle, content and collections, and feature availability events track the store itself changing, and they are what an automation tool listens to to keep a storefront current without anyone rebuilding it. A store rarely arrives fully formed. A merchant starts with a thin catalog and no reviews, no promotions, and no published content, leaving the matching storefront surfaces with nothing to show. As the store fills in, these events mark the moment each surface has something behind it:

promotion.activated carries the live promotion a banner and product badges render from, and promotion.deactivated marks when they stop applying.
review.approved is the point at which a product page has a real review behind its star summary and reviews block.
collection.updated covers a banner being added, show_on_homepage being turned on, and membership changing, the last carrying members_changed: true and calling for a re-read of the collection’s products. Membership churn is not only a manual edit: a merchant can set a collection to refresh itself on a schedule, so a shelf like “current best sellers” changes contents on its own. The event fires once per collection per change rather than once per product, so a ten-product rotation is one event.
pricing_rule.activated / .updated / .deactivated bound the validity of a cached price. A dynamic-pricing rule changes what every shopper pays without touching a single product record, so a cached price is stale from the moment one of these fires.
feature.status_changed (awaiting_data → available) is the moment a capability’s data exists — recommendations shelves once there is enough signal, a currency switcher once a second currency is configured. A not_in_plan → available transition is the same signal arriving after a plan upgrade unlocks the capability.

Anvil, Tybrite Labs’ autonomous storefront studio, builds its self-improving storefronts on exactly these events: it subscribes, and when one fires it proposes the matching storefront change for the merchant to preview and approve, without a rebuild or downtime. The same events are available to any tool.

What’s next

Pair feed.sync.completed with the inbound importer in Catalog Sync to close the loop on scheduled syncs.
See where order.paid comes from in the Storefront checkout flow.
See the full envelope shape and per-event payloads in the Webhooks reference.

Overview

Storefront

Marketplace

Integrations

Reference

1. Registering an endpoint

2. Listing and inspecting endpoints and their health

3. Health degradation and auto-disable

4. The event envelope

5. Verifying the signature in your handler

6. Testing, auditing, and retrying deliveries

7. Handling `order.paid` end to end

Supported event types

Keeping a storefront in step with the store

What’s next

​1. Registering an endpoint

​2. Listing and inspecting endpoints and their health

​3. Health degradation and auto-disable

​4. The event envelope

​5. Verifying the signature in your handler

​6. Testing, auditing, and retrying deliveries

​7. Handling order.paid end to end

​Supported event types

​Keeping a storefront in step with the store

​What’s next

1. Registering an endpoint

2. Listing and inspecting endpoints and their health

3. Health degradation and auto-disable

4. The event envelope

5. Verifying the signature in your handler

6. Testing, auditing, and retrying deliveries

7. Handling `order.paid` end to end

Supported event types

Keeping a storefront in step with the store

What’s next