Webhooks

Use webhooks when another system must react to workspace events. Keep the first version narrow and observable.

Setup Decisions

Handler Rules

• Verify the event before doing business work.
• Return quickly and process slow work asynchronously.
• Make repeated deliveries safe.
• Store only the fields needed for operations and audit.

Order-Change Events

Admin Panel drag-and-drop ordering is delivered as a normal collection update with semantic metadata. Branch through the SDK helper and route on public semantics such as change.scope and change.moved.id.

import { handleWebhook, isOrderChangedWebhookEvent } from '@01.software/sdk/webhook'

function getWebhookSecret(): string {
  const secret = process.env.WEBHOOK_SECRET
  if (!secret) throw new Error('WEBHOOK_SECRET is required')
  return secret
}

export async function POST(request: Request) {
  return handleWebhook(
    request,
    async (event) => {
      if (isOrderChangedWebhookEvent(event)) {
        if (event.change.scope.kind === 'join') {
          console.log('Join order changed', {
            collection: event.change.scope.collection,
            field: event.change.scope.field,
            parentId: event.change.scope.id,
            movedCollection: event.change.moved.collection,
            movedId: event.change.moved.id,
          })
        }
        return
      }

      console.log('Content changed', event.collection, event.operation)
    },
    { secret: getWebhookSecret() },
  )
}

Order-change events keep operation: "update" and add eventType: "collection.orderChanged". For join ordering, change.moved identifies the public moved entity when one exists. Handlers should not branch on hidden Payload order fields or private backing collections.

Customer group member ordering is currently treated as an unsupported hidden join-order surface and does not emit a semantic order-change webhook.

Operations

• Track delivery failures as launch blockers when the flow is customer-facing.
• Keep a manual recovery path for orders, payments, account changes, and fulfillment.
• Rotate webhook secrets when ownership is unclear.

Next Actions

• Need credentials: open Authentication & Keys.
• Need HTTP details: open API.
• Need final checks: open Launch Readiness.