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

# Create Webhook

> Create a signed webhook endpoint

## Create Webhook

Creates an endpoint. The response returns the full signing secret, so store it now. The API never returns it again; you can see it again or rotate it in the app under **Settings → Agents & Integrations → Webhooks**.

### Request

**workspace\_id** `integer` *required*

The workspace the endpoint belongs to

**name** `string` *required*

Display name of the endpoint

**url** `string` *required*

A public `https` address. Private and reserved addresses are refused.

**events** `array` *required*

Event keys the endpoint gets, such as `post.failed`. See [Webhooks](https://docs.postsyncer.com/api-reference/webhooks/overview.md) for the list.

**account\_ids** `array`

Only send events about these social accounts. Leave out for all accounts.

**workspace\_ids** `array`

Also send events from these workspaces, or `["*"]` for every workspace you own. You must be an owner or manager of each one, and only the workspace owner can use `"*"`.

```json theme={null}
{
  "workspace_id": 12,
  "name": "Ops alerts",
  "url": "https://example.com/postsyncer-hook",
  "events": ["post.failed", "post.published"]
}
```

### Response

Status `201`. The endpoint object, plus:

**secret** `string`

The signing secret in full, starting with `whsec_`. The API returns it only in this response.

**id** `integer`

Unique identifier of the endpoint

**name** `string`

Display name of the endpoint

**url** `string`

The https address that receives the events. An address can carry a token, so it is shown in full only when the key's owner may edit the endpoint (`notifications` edit in its workspace, and in every workspace it covers). Otherwise it is cut to the scheme and host, such as `https://example.com/…`.

**url\_masked** `boolean`

`true` when `url` was cut because the key's owner may not edit the endpoint

**secret\_last4** `string`

The last four characters of the signing secret. The API returns the full secret only when you create the endpoint; the app can show it again.

**events** `array`

Event keys the endpoint gets

**account\_ids** `array`

Social account ids the endpoint is limited to, or `null` for all accounts

**workspace\_ids** `array`

Other workspaces whose events it also gets (`["*"]` for every workspace the creator owns), or `null`

**active** `boolean`

Whether the endpoint is on. PostSyncer turns an endpoint off after it has been failing for 3 days.

**failing\_since** `string`

When the endpoint started failing, or `null`

**disabled\_reason** `string`

Why PostSyncer turned the endpoint off, or `null`

**stats\_7d** `object`

Deliveries over the last 7 days: `sent`, `failed` and `daily`, seven entries with the oldest first

**last\_delivery\_at** `string`

When the latest delivery was made, or `null`

```json theme={null}
{
  "id": 42,
  "workspace_id": 12,
  "kind": "webhook",
  "name": "Ops alerts",
  "url": "https://example.com/postsyncer-hook",
  "url_masked": false,
  "secret": "whsec_Zm9vYmFyYmF6cXV4a2VlcGl0c2VjcmV0MTIzNA==",
  "secret_last4": "NA==",
  "events": ["post.failed", "post.published"],
  "account_ids": null,
  "workspace_ids": null,
  "active": true,
  "failing_since": null,
  "disabled_reason": null,
  "created_at": "2026-11-15T09:30:00+00:00",
  "updated_at": "2026-11-15T09:30:00+00:00",
  "stats_7d": {
    "sent": 18,
    "failed": 1,
    "daily": [
      { "date": "2026-11-09", "sent": 0, "failed": 0 },
      { "date": "2026-11-10", "sent": 3, "failed": 0 },
      { "date": "2026-11-11", "sent": 2, "failed": 1 },
      { "date": "2026-11-12", "sent": 4, "failed": 0 },
      { "date": "2026-11-13", "sent": 3, "failed": 0 },
      { "date": "2026-11-14", "sent": 5, "failed": 0 },
      { "date": "2026-11-15", "sent": 1, "failed": 0 }
    ]
  },
  "last_delivery_at": "2026-11-15T09:12:44+00:00"
}
```

### Errors

| Status | Cause |
| - | - |
| `403` | Your key lacks `webhooks:create`, or you are not an owner or manager of a covered workspace |
| `422` | The address is not https or not public, an event is unknown, the workspace already has 20 endpoints |

### Code Examples

```bash cURL theme={null}
curl -X POST "https://postsyncer.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 12,
    "name": "Ops alerts",
    "url": "https://example.com/postsyncer-hook",
    "events": ["post.failed", "post.published"]
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://postsyncer.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workspace_id: 12,
    name: 'Ops alerts',
    url: 'https://example.com/postsyncer-hook',
    events: ['post.failed', 'post.published'],
  }),
});

const webhook = await response.json();
console.log(webhook.secret); // store this now
```

```python Python theme={null}
import requests

response = requests.post(
    "https://postsyncer.com/api/v1/webhooks",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={
        "workspace_id": 12,
        "name": "Ops alerts",
        "url": "https://example.com/postsyncer-hook",
        "events": ["post.failed", "post.published"],
    },
)
print(response.json()["secret"])  # store this now
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.