# Webhooks

Receive signed Naasher events, verify HMAC over the raw body, and process deliveries safely.

[العربية](/webhooks)

Naasher sends signed events to registered HTTPS destinations so an authorized system can react to recorded state changes. Webhooks are available on the **Teams** and **Agency** plans.

## [Register an endpoint](#register-an-endpoint)

Create a registration under **Settings → Developers → Webhooks**, or use the REST API:

```
curl -X POST https://api.naasher.com/api/sdk/v1/webhooks \
  -H "x-naasher-api-key: $NAASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/naasher", "events": ["post.published", "post.failed"] }'
```

The signing secret is shown once. Store it in a secret manager, separate production and test endpoints, and rotate it after exposure or ownership changes.

## [Event catalog](#event-catalog)

| Event                   | Recorded transition                          |
| ----------------------- | -------------------------------------------- |
| post.created            | A post record was created                    |
| post.scheduled          | A post was scheduled                         |
| post.publishing         | Provider publishing began                    |
| post.published          | A provider target reported success           |
| post.failed             | A provider target reported failure           |
| post.deleted            | A post record was deleted                    |
| channel.connected       | A social account was connected               |
| channel.disconnected    | A social account was disconnected            |
| channel.token\_expiring | A provider grant is approaching expiry       |
| channel.token\_expired  | Reconnection is required                     |
| inbox.comment\_received | A supported comment arrived                  |
| report.weekly           | The weekly report is ready                   |
| queue.low               | A recurring publishing queue is nearly empty |
| webhook.test            | A manual delivery test was requested         |

An event reports Naasher's recorded transition. For a critical external action, retain the target identifier and reconcile the provider-visible result as well.

## [Verify the signature](#verify-the-signature)

`Naasher-Signature` contains a Unix timestamp and HMAC value:

```
t=1752163200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

Compute `HMAC-SHA256` over `"{timestamp}.{raw_body}"`, compare in constant time, and reject stale timestamps. A five-minute window is a reasonable starting policy for many systems, but choose one that matches the controlled queue and clock guarantees.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyNaasherWebhook(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  const want = Buffer.from(expected, 'hex');
  return given.length === want.length && timingSafeEqual(given, want);
}
```

Verify the raw request body

Calculate the signature before parsing or re-serializing JSON. Reordered keys or normalized whitespace change the signed bytes.

## [Delivery and retries](#delivery-and-retries)

Return `2xx` quickly after durable receipt, then process asynchronously. Naasher retries transient network and `5xx` failures with increasing delay. Your consumer must deduplicate repeated event deliveries and must not turn a duplicate delivery into a repeated publish or customer notification.

Use the [REST API](/en/api) to fetch current state when an event is late or missing, and keep secrets and raw customer content out of public delivery logs.

[MCP serverConnect a scoped AI client to Naasher through Streamable HTTP while keeping human approval before external actions.](/en/mcp)[Plans and billingPublic plan limits, account and workspace overages, trials, cancellation, and the unresolved edges of X usage.](/en/billing)

---

Canonical URL: https://docs.naasher.com/en/webhooks