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

# Ordinal webhooks

> Get real-time notifications on events across your Ordinal workspace

<Frame>
  <img src="https://mintcdn.com/ordinal/DKeSUHVr5PHY1VA-/images/Webhooks---Asset.jpg?fit=max&auto=format&n=DKeSUHVr5PHY1VA-&q=85&s=13b63ba8f4dea9b46e8830c0dbcc243a" alt="Webhooks Asset" width="3342" height="1828" data-path="images/Webhooks---Asset.jpg" />
</Frame>

Use webhooks to get real-time notifications on events happening across your Ordinal workspace. With Ordinal webhooks, you can build custom integrations, such as:

* Syncing post data to your CRM when content goes live
* Auto-create Linear tickets based on changes in a post's status
* Sync approval workflows with your company's existing compliance tooling
* Trigger onboarding sequences in your own systems when new teammates accept invites
* Feed campaign activity into custom executive dashboards
* Building internal dashboards that track publishing activity across your team

In this guide, we'll show you how to configure webhooks and document the available events you can listen to.

## Managing webhooks

You can manage webhooks via the dashboard or the API.

**Dashboard:** Navigate to [**Settings → Integrations → Webhooks**](https://app.tryordinal.com/settings/integrations/webhooks) to create, view, edit, and delete webhooks.

**API:** The webhooks API supports full CRUD operations. All endpoints require [API key authentication](/api/authentication).

| Operation | Method   | Endpoint         | Description                         |
| --------- | -------- | ---------------- | ----------------------------------- |
| List      | `GET`    | `/webhooks`      | List all webhooks for the workspace |
| Create    | `POST`   | `/webhooks`      | Create a new webhook                |
| Get       | `GET`    | `/webhooks/{id}` | Get a webhook by ID                 |
| Update    | `PATCH`  | `/webhooks/{id}` | Update an existing webhook          |
| Delete    | `DELETE` | `/webhooks/{id}` | Delete a webhook                    |

### List webhooks

```bash theme={null}
curl -X GET "https://app.tryordinal.com/api/v1/webhooks" \
  -H "Authorization: Bearer your_api_key"
```

Response:

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440900",
    "name": "CRM Sync",
    "url": "https://example.com/webhooks/ordinal",
    "description": "Sync published posts to our CRM",
    "headers": { "X-Custom-Header": "value" },
    "topics": ["post.published", "post.archived"],
    "createdAt": "2026-01-15T10:00:00.000Z",
    "createdBy": {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "email": "john@acme.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
]
```

### Create webhook

```bash theme={null}
curl -X POST "https://app.tryordinal.com/api/v1/webhooks" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Sync",
    "url": "https://example.com/webhooks/ordinal",
    "description": "Sync published posts to our CRM",
    "topics": ["post.published", "post.archived"],
    "headers": { "X-Custom-Header": "value" }
  }'
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440900",
  "name": "CRM Sync",
  "url": "https://example.com/webhooks/ordinal",
  "topics": ["post.published", "post.archived"],
  "createdAt": "2026-01-15T10:00:00.000Z"
}
```

(Note: Create response omits `description`, `headers`, and `createdBy`; use Get for the full webhook object.)

### Get webhook

```bash theme={null}
curl -X GET "https://app.tryordinal.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440900" \
  -H "Authorization: Bearer your_api_key"
```

### Update webhook

Send only the fields you want to change. All request body fields are optional.

```bash theme={null}
curl -X PATCH "https://app.tryordinal.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440900" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated CRM Sync",
    "topics": ["post.published", "post.archived", "post.content.edited"]
  }'
```

### Delete webhook

```bash theme={null}
curl -X DELETE "https://app.tryordinal.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440900" \
  -H "Authorization: Bearer your_api_key"
```

Response:

```json theme={null}
{
  "success": true
}
```

See the [Webhooks API reference](/api-reference/webhooks/list-webhooks) for full request/response schemas, valid event types, and error handling.

## Payload format

All webhook deliveries use the same envelope. The request body is JSON:

```json theme={null}
{
  "type": "post.published",
  "data": { ... },
  "createdAt": "2025-02-26T14:30:00.000Z"
}
```

| Field       | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `type`      | The event type (e.g. `post.published`, `post.archived`)     |
| `data`      | Event-specific payload. See each event page for the schema. |
| `createdAt` | ISO 8601 timestamp when the event was emitted               |

Your endpoint should respond with a `2xx` status code to acknowledge receipt.

See [Event types](/integrations/webhooks/event-types) for the full list of supported events and links to each payload schema.