> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive OrgX events in your own systems.

Webhooks let OrgX notify your systems when work changes. Use them for external
queues, CRM updates, compliance archives, alerting, or workflow automation.

<Info>
  Webhooks are in Public Preview. Contact [hello@useorgx.com](mailto:hello@useorgx.com)
  to enable webhook delivery for a workspace.
</Info>

## Event Types

| Event                | When it fires                                 |
| -------------------- | --------------------------------------------- |
| `decision.created`   | A decision needs review.                      |
| `decision.resolved`  | A decision was approved or rejected.          |
| `artifact.shipped`   | An approved artifact is ready.                |
| `agent.started`      | An agent run began.                           |
| `agent.completed`    | An agent run completed.                       |
| `initiative.updated` | Initiative progress, risk, or status changed. |

## Payload

```json theme={"dark"}
{
  "id": "evt_01h...",
  "type": "decision.created",
  "created": "2026-04-29T20:00:00Z",
  "workspace_id": "d85d7e6f-58f2-4637-b3a0-3cf2c3b8a638",
  "data": {
    "id": "dec_123",
    "title": "Campaign brief ready",
    "urgency": "high"
  }
}
```

## Signature Header

Webhook requests include an HMAC signature.

```text theme={"dark"}
X-OrgX-Signature: sha256=...
```

Verify the signature before processing the event. Reject unsigned requests.

## Delivery Contract

Webhook delivery is enabled per workspace during Public Preview. Exact retry
windows and timeout values are confirmed during enablement.

| Behavior      | Contract                           |
| ------------- | ---------------------------------- |
| Method        | `POST`                             |
| Content type  | `application/json`                 |
| Timeout       | Workspace-specific preview timeout |
| Retries       | Configured during enablement       |
| Ordering      | Events may arrive out of order     |
| Deduplication | Use the event `id` as a dedupe key |

## Handler Example

```ts theme={"dark"}
export async function POST(request: Request) {
  const signature = request.headers.get('x-orgx-signature');
  const body = await request.text();

  if (!signature || !verifyOrgxSignature(body, signature)) {
    return new Response('invalid signature', { status: 401 });
  }

  const event = JSON.parse(body);
  await processOrgxEvent(event);

  return Response.json({ received: true });
}
```