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

# Webhooks

> Hear when your users connect apps, finish syncs, change plans or are deleted.

**1. Set the link**

In [Projects](https://www.constella.app/console?tab=projects), set an `https` webhook link on your project. Its signing secret is shown once: keep it on your server. A link to a private address is refused.

**2. Check each call**

Every `POST` carries `Constella-Signature: t=<unix>,v1=<hex>`: an HMAC-SHA256 of `<t>.<body>` with your secret.

```python Python theme={"system"}
import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False
    mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])
```

```javascript Node.js theme={"system"}
import crypto from "node:crypto";

export function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1));
}
```

**3. Answer with any 2xx**

A failed delivery is tried again after 30 seconds, then up to 5 more times (2 min, 8 min, 32 min, then hourly).

## The events

Every event has the same shape:

```json theme={"system"}
{
  "id": "evt_3f9a...",
  "type": "sync.initial_completed",
  "app_id": "myappx7k2",
  "external_user_id": "u_123",
  "created_at": "2026-11-18T09:12:00Z",
  "data": {"integration": "notion", "records": 412}
}
```

| Type | When | `data` |
| - | - | - |
| `connection.connected` | A user connected an app. | `integration` |
| `connection.failed` | Connecting failed. | `integration`, `reason` |
| `connection.disconnected` | An app was disconnected. | `integration` |
| `sync.initial_completed` | The first sync of an app finished. | `integration`, `records` |
| `sync.updated` | New items arrived from an app. | `integration`, `new_records`, `records` |
| `plan.changed` | A user's plan changed. | `kind` and details |
| `tenant.deleted` | Deleting a user finished. | `errors` |


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