# Webhooks

> Receive signed events for posts, accounts, the inbox, messaging, ads and billing, verify their signatures and handle retries.

Webhooks send a `POST` request to your URL when something happens in your workspace. Create endpoints in **Manage → Webhooks** or with the [Webhooks API](/docs/api-reference/webhooks/) (MCP toolset `webhooks`), and subscribe to every event or a list.

```bash
curl -X POST https://api.socialit.com/v1/webhooks \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production", "url": "https://your-app.com/socialit/webhooks", "events": ["post.published", "post.failed", "message.received"] }'
```

The response includes the signing `secret` (or bring your own with `secret`). `profile_ids` limits an endpoint to events of some profiles; `all_events: true` subscribes to everything, including event types added later.

## Payload

Every delivery has the same envelope; `data` depends on the event type.

```json
{
  "id": "evt_9Qw2Lm4Rt6Yp1Xn3Vb8Kd5SzHc2",
  "object": "event",
  "type": "post.published",
  "created_at": "2026-10-14T09:00:04.512Z",
  "workspace_id": "ws_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
  "test": false,
  "data": {
    "post": {
      "object": "post",
      "id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd",
      "status": "published",
      "postings": [{ "object": "posting", "platform": "instagram", "status": "published", "url": "https://www.instagram.com/p/…" }]
    }
  }
}
```

Headers: `X-Socialit-Signature`, `X-Socialit-Timestamp`, `X-Socialit-Event` (the type) and `X-Socialit-Delivery` (the delivery ID).

## Event types

Socialit emits about 90 event types across posts, accounts, the inbox, contacts and automations, ads, analytics and billing. The [Webhook events reference](/docs/api-reference/webhook-events/) lists every one with its payload, generated from the same catalog the API validates subscriptions against (`GET /v1/events/names`). `GET /v1/events` is the event log: the same payloads, kept for replay and debugging.

## Verify the signature

Every delivery has two headers:

- `X-Socialit-Timestamp`: Unix time in seconds when the delivery was signed.
- `X-Socialit-Signature`: hex HMAC-SHA256 of `${timestamp}.${body}` with your endpoint's secret.

Compute the HMAC over the **raw** request body, compare in constant time, and reject timestamps older than five minutes to stop replays.

**Node.js**

```js

export function verify(rawBody, headers, secret) {
  const timestamp = headers['x-socialit-timestamp'];
  const signature = headers['x-socialit-signature'];
  if (!timestamp || !signature || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```

**Python**

```python

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Socialit-Timestamp")
    signature = headers.get("X-Socialit-Signature")
    if not timestamp or not signature or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)
```

**PHP**

```php
<?php
function verify(string $rawBody, array $headers, string $secret): bool {
    $timestamp = $headers['X-Socialit-Timestamp'] ?? null;
    $signature = $headers['X-Socialit-Signature'] ?? null;
    if (!$timestamp || !$signature || abs(time() - (int) $timestamp) > 300) return false;
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}
```

## Responding and retries

Answer with any `2xx` status quickly, and do slow work after responding. Socialit retries failed deliveries after **5 minutes, 30 minutes, 2 hours and 5 hours, then every 12 hours**, up to **11 attempts**. An endpoint that keeps failing for 3 days is disabled automatically.

Deliveries can arrive more than once and out of order: use the event `id` to deduplicate and `created_at` to order.

## Tools

- `POST /v1/webhooks/{id}/test` sends a test event of the type you choose.
- `GET /v1/webhooks/{id}/deliveries` lists recent deliveries with status codes and response bodies.
- `POST /v1/webhooks/deliveries/{id}/redeliver` sends one again; `POST /v1/webhooks/{id}/retry-failed` retries all failed ones.
- `POST /v1/webhooks/{id}/reset-secret` rotates the signing secret.

---

Source: https://socialit.com/docs/webhooks/
