Webhooks

Delivery

Every event is a POST to your webhook URL with a JSON body and these headers:

Header	Value
`Content-Type`	`application/json`
`X-Verso-Event`	The event name, e.g. `connection.created`
`X-Verso-Signature`	`t=<unix seconds>,v1=<hmac>`; present when a webhook secret is configured for your app

{
  "event": "connection.created",
  "payload": { "...": "..." },
  "deliveryId": "770e8400-e29b-41d4-a716-446655440000"
}

deliveryId identifies the delivery, not the event: a retried delivery keeps the same id. Use it to ignore duplicates.

Events

Event	Sent when
`connect.started`	The user opened a connect link and the login page started
`connection.created`	The user logged in; a connection exists and its first sync is starting
`data.imported`	A sync or an export ingestion inserted or updated at least one conversation
`reauth.needed`	The provider rejected the stored session; the user must connect again
`data.deleted`	All data of a user in your app was deleted (manage page or user purge)
`connection.deleted`	One connection was deleted through the purge API

Every payload includes userRef, the identifier you passed to signLink(), so you can route the event without a lookup.

`connect.started`

{
  "event": "connect.started",
  "payload": {
    "userRef": "user_123",
    "user_id": "660e8400-e29b-41d4-a716-446655440000",
    "connector": "chatgpt",
    "scopes": ["conversations:read"]
  },
  "deliveryId": "…"
}

user_id is Verso’s internal id for the user. Nothing is connected yet; the user may still abandon the page.

`connection.created`

{
  "event": "connection.created",
  "payload": {
    "connectionId": "550e8400-e29b-41d4-a716-446655440000",
    "userRef": "user_123",
    "userId": "660e8400-e29b-41d4-a716-446655440000",
    "connectorId": "chatgpt-live",
    "provider": "chatgpt",
    "replaces": ["440e8400-e29b-41d4-a716-446655440000"]
  },
  "deliveryId": "…"
}

replaces lists previous connections of the same user and provider account, now revoked. Their conversations moved to connectionId. It is empty on a first connection.

`data.imported`

{
  "event": "data.imported",
  "payload": {
    "connectionId": "550e8400-e29b-41d4-a716-446655440000",
    "userRef": "user_123",
    "inserted": 12,
    "updated": 3,
    "unchanged": 127,
    "total": 142,
    "importedAt": "2026-09-29T03:00:12.000Z"
  },
  "deliveryId": "…"
}

Not sent when a sync finds nothing new. inserted counts conversations seen for the first time, which during the initial backfill includes old history; use GET /api/connections for recent activity.

`reauth.needed`

{
  "event": "reauth.needed",
  "payload": {
    "connectionId": "550e8400-e29b-41d4-a716-446655440000",
    "userRef": "user_123",
    "provider": "chatgpt",
    "reason": "401: conversation listing rejected",
    "lastSuccessfulPull": "2026-09-27T03:00:12.000Z"
  },
  "deliveryId": "…"
}

Sign a new connect link for the user. Until they reconnect, the connection stays needs_reauth and its conversations remain readable.

`data.deleted`

{
  "event": "data.deleted",
  "payload": {
    "userRef": "user_123",
    "providers": ["chatgpt"],
    "connectionIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "conversationsDeleted": 142,
    "deletedAt": "2026-09-29T16:00:00.000Z"
  },
  "deliveryId": "…"
}

`connection.deleted`

{
  "event": "connection.deleted",
  "payload": {
    "connectionId": "550e8400-e29b-41d4-a716-446655440000",
    "userRef": "user_123",
    "provider": "chatgpt",
    "conversationsDeleted": 142,
    "deletedAt": "2026-09-29T16:00:00.000Z"
  },
  "deliveryId": "…"
}

Verifying signatures

The signature is Stripe-style: t is the Unix timestamp of the delivery, v1 is HMAC-SHA256(secret, t + "." + body) in hex. Verify on the raw body.

import { verifyWebhook } from "@versoai/core";

app.post("/webhooks/verso", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  if (!verifyWebhook(process.env.VERSO_WEBHOOK_SECRET!, req.get("x-verso-signature") ?? "", body)) {
    return res.status(401).end();
  }
  // …
});

verifyWebhook rejects signatures older than 5 minutes by default; pass a fourth argument to change the tolerance. Without the SDK:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, header: string, body: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=", 2)));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${parts.t}.${body}`).digest("hex");
  return expected.length === parts.v1.length &&
    timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1, "hex"));
}

Retries

Your endpoint must answer with a 2xx status within 10 seconds. Anything else, including a timeout, counts as a failure and the delivery is retried with exponential backoff, six attempts in total.

Attempt	Delay after the previous one
1	immediate
2	2 minutes
3	4 minutes
4	8 minutes
5	16 minutes
6	32 minutes

After the sixth failure the delivery is dropped. Deliveries are independent: a retried event can arrive after a newer one, so do not rely on ordering. If your app has no webhook URL configured, events are discarded.

Getting started

Guides

Resources

Delivery

Events

`connect.started`

`connection.created`

`data.imported`

`reauth.needed`

`data.deleted`

`connection.deleted`

Verifying signatures

Retries

​Delivery

​Events

​connect.started

​connection.created

​data.imported

​reauth.needed

​data.deleted

​connection.deleted

​Verifying signatures

​Retries

Delivery

Events

`connect.started`

`connection.created`

`data.imported`

`reauth.needed`

`data.deleted`

`connection.deleted`

Verifying signatures

Retries