# Webhooks API

> Signed HTTPS callbacks for workspace events. Each delivery carries X-Socialit-Signature (hex HMAC-SHA256 of ${timestamp}.${body} with the webhook secret) and X-Socialit-Timestamp. Failed deliveries retry after 5m, 30m, 2h, 5h, then every 12h (11 attempts); a webhook failing for 3 days is disabled.

Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer <API key or OAuth token>`.

## List webhooks

`GET /webhooks`

Access: `admin` · MCP tool: `list-webhooks` · Zernio: `GET /v1/webhooks/settings`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, name, last_delivery_at)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `enabled` (string)

```bash
curl "https://api.socialit.com/v1/webhooks" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "string",
      "name": "string",
      "url": "https://example.com",
      "enabled": true,
      "all_events": true,
      "events": [
        "string"
      ],
      "profile_ids": [
        "string"
      ],
      "secret": "string",
      "last_delivery_at": "2026-10-13T09:00:00.000Z",
      "failure_count": 1,
      "disabled_reason": "string",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a webhook

`POST /webhooks`

The response contains the signing secret; it is only shown again after reset-secret.

Access: `admin` · MCP tool: `create-webhook` · Zernio: `POST /v1/webhooks/settings`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–100 characters)
- `url` (string; required; 8–2048 characters)
- `events` (array of string; ≤ 200 items, unique)
- `all_events` (boolean)
- `profile_ids` (array of string | null; ≤ 500 items)
- `enabled` (boolean)
- `secret` (string; 16–256 characters): Bring your own signing secret (default: generated)

```bash
curl -X POST "https://api.socialit.com/v1/webhooks" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "url": "https://example.com",
    "events": [
      "*"
    ],
    "all_events": true,
    "profile_ids": [
      "string"
    ]
  }'
```

Response 201:

```json
{
  "object": "webhook",
  "id": "string",
  "name": "string",
  "url": "https://example.com",
  "enabled": true,
  "all_events": true,
  "events": [
    "string"
  ],
  "profile_ids": [
    "string"
  ],
  "secret": "string",
  "last_delivery_at": "2026-10-13T09:00:00.000Z",
  "failure_count": 1,
  "disabled_reason": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Get a webhook

`GET /webhooks/{id}`

Access: `admin` · MCP tool: `get-webhook`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

```bash
curl "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "webhook",
  "id": "string",
  "name": "string",
  "url": "https://example.com",
  "enabled": true,
  "all_events": true,
  "events": [
    "string"
  ],
  "profile_ids": [
    "string"
  ],
  "secret": "string",
  "last_delivery_at": "2026-10-13T09:00:00.000Z",
  "failure_count": 1,
  "disabled_reason": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Update a webhook

`PATCH /webhooks/{id}`

Re-enabling a disabled webhook resets its failure streak.

Access: `admin` · MCP tool: `update-webhook` · Zernio: `PUT /v1/webhooks/settings`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

### Body

- `name` (string; 1–100 characters)
- `url` (string; 8–2048 characters)
- `events` (array of string; ≤ 200 items, unique)
- `all_events` (boolean)
- `profile_ids` (array of string | null; ≤ 500 items)
- `enabled` (boolean)

```bash
curl -X PATCH "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "url": "https://example.com",
    "events": [
      "*"
    ],
    "all_events": true,
    "profile_ids": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "webhook",
  "id": "string",
  "name": "string",
  "url": "https://example.com",
  "enabled": true,
  "all_events": true,
  "events": [
    "string"
  ],
  "profile_ids": [
    "string"
  ],
  "secret": "string",
  "last_delivery_at": "2026-10-13T09:00:00.000Z",
  "failure_count": 1,
  "disabled_reason": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Delete a webhook

`DELETE /webhooks/{id}`

Access: `admin` · MCP tool: `delete-webhook` · Zernio: `DELETE /v1/webhooks/settings`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

```bash
curl -X DELETE "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "webhook",
  "id": "string",
  "deleted": true
}
```

## Send a test event

`POST /webhooks/{id}/test`

Sends one signed sample event now and returns the receiver response. Not retried.

Access: `admin` · MCP tool: `test-webhook` · Zernio: `POST /v1/webhooks/test`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

### Body

- `type` (string; one of post.scheduled, post.publishing, post.published, post.partially_published, post.failed, post.deleted, post.unpublished, post.cancelled, post.edited, post.recycled, post.approval_requested, post.approved, …): Sample event type (default webhook.test)

```bash
curl -X POST "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/test" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "post.scheduled"
  }'
```

Response 200:

```json
{
  "object": "webhook_test",
  "success": true,
  "status_code": 1,
  "duration_ms": 1,
  "response_body": "string",
  "error": "string",
  "delivery": {
    "object": "webhook_delivery",
    "id": "string",
    "webhook_id": "string",
    "event_id": "string",
    "event_type": "string",
    "attempt": 1,
    "status": "pending",
    "status_code": 1,
    "response_body": "string",
    "error": "string",
    "duration_ms": 1,
    "test": true,
    "next_retry_at": "2026-10-13T09:00:00.000Z",
    "created_at": "2026-10-13T09:00:00.000Z",
    "delivered_at": "2026-10-13T09:00:00.000Z"
  }
}
```

## Rotate the signing secret

`POST /webhooks/{id}/reset-secret`

Access: `admin` · MCP tool: `reset-webhook-secret`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

```bash
curl -X POST "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reset-secret" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "webhook",
  "id": "string",
  "name": "string",
  "url": "https://example.com",
  "enabled": true,
  "all_events": true,
  "events": [
    "string"
  ],
  "profile_ids": [
    "string"
  ],
  "secret": "string",
  "last_delivery_at": "2026-10-13T09:00:00.000Z",
  "failure_count": 1,
  "disabled_reason": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## List webhook deliveries

`GET /webhooks/deliveries`

Delivery log across every webhook of the workspace.

Access: `admin` · MCP tool: `list-all-webhook-deliveries` · Zernio: `GET /v1/webhooks/logs`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, status_code, attempt)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `status` (string)
- `event_type` (string)
- `webhook_id` (string)
- `event_id` (string)

```bash
curl "https://api.socialit.com/v1/webhooks/deliveries" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "string",
      "webhook_id": "string",
      "event_id": "string",
      "event_type": "string",
      "attempt": 1,
      "status": "pending",
      "status_code": 1,
      "response_body": "string",
      "error": "string",
      "duration_ms": 1,
      "test": true,
      "next_retry_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "delivered_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get a webhook delivery

`GET /webhooks/deliveries/{id}`

Access: `admin` · MCP tool: `get-webhook-delivery`

### Path parameters

- `id` (string; required; 1–80 characters): webhookDelivery id (whd_…)

```bash
curl "https://api.socialit.com/v1/webhooks/deliveries/whd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "webhook_delivery",
  "id": "string",
  "webhook_id": "string",
  "event_id": "string",
  "event_type": "string",
  "attempt": 1,
  "status": "pending",
  "status_code": 1,
  "response_body": "string",
  "error": "string",
  "duration_ms": 1,
  "test": true,
  "next_retry_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "delivered_at": "2026-10-13T09:00:00.000Z"
}
```

## Redeliver an event

`POST /webhooks/deliveries/{id}/redeliver`

Queues a new delivery of the same event to the same webhook.

Access: `admin` · MCP tool: `redeliver-webhook-delivery` · Zernio: `POST /v1/webhooks/logs/redeliver`

### Path parameters

- `id` (string; required; 1–80 characters): webhookDelivery id (whd_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/webhooks/deliveries/whd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/redeliver" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 201:

```json
{
  "object": "webhook_delivery",
  "id": "string",
  "webhook_id": "string",
  "event_id": "string",
  "event_type": "string",
  "attempt": 1,
  "status": "pending",
  "status_code": 1,
  "response_body": "string",
  "error": "string",
  "duration_ms": 1,
  "test": true,
  "next_retry_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "delivered_at": "2026-10-13T09:00:00.000Z"
}
```

## List a webhook's deliveries

`GET /webhooks/{id}/deliveries`

Access: `admin` · MCP tool: `list-webhook-deliveries`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, status_code, attempt)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `status` (string)
- `event_type` (string)
- `webhook_id` (string)
- `event_id` (string)

```bash
curl "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/deliveries" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "string",
      "webhook_id": "string",
      "event_id": "string",
      "event_type": "string",
      "attempt": 1,
      "status": "pending",
      "status_code": 1,
      "response_body": "string",
      "error": "string",
      "duration_ms": 1,
      "test": true,
      "next_retry_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "delivered_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Retry failed deliveries

`POST /webhooks/{id}/retry-failed`

Re-queues failed deliveries from the last 3 days.

Access: `admin` · MCP tool: `retry-failed-webhook-deliveries`

### Path parameters

- `id` (string; required; 1–80 characters): webhook id (wh_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/retry-failed" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 200:

```json
{
  "object": "webhook_retry",
  "webhook_id": "string",
  "retried": 1
}
```


---

Source: https://socialit.com/docs/api-reference/webhooks/
