Webhooks

​

Available events

​

Scopes your app needs

​

Subscribe after install

curl -X POST https://app.useorbitcrm.ai/api/v1/webhooks \
  -H "Authorization: Bearer $WORKSPACE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: install-$INSTALLATION_ID" \
  -d '{
    "url": "https://yourapp.example/orbit/events?workspace='"$INSTALLATION_ID"'",
    "events": ["contact.created", "contact.updated", "deal.created", "deal.stage_changed", "meeting.booked", "call.analyzed"]
  }'

{
  "data": {
    "id": "f0e1d2c3-...",
    "url": "https://yourapp.example/orbit/events?workspace=...",
    "events": ["contact.created", "contact.updated", "deal.created", "deal.stage_changed", "meeting.booked", "call.analyzed"],
    "is_active": true,
    "form_id": null,
    "created_at": "2026-10-27T14:00:00Z",
    "secret": "a1b2c3...64 hex characters"
  },
  "message": "Webhook created. Save the secret - it will only be shown once."
}

• The Idempotency-Key makes the call safe to retry; a replay returns the webhook without the secret.
• Your app only ever sees the webhooks it registered. GET /api/v1/webhooks with a workspace’s token lists yours in that workspace.
• Limits: 5 webhooks per workspace while your app is in development, 100 once it is approved. Creation is rate limited to 60 an hour per app per workspace (500 once approved); the response and a 429 carry RateLimit-* headers. One webhook can subscribe to any number of events (X-Orbit-Event and the envelope’s event say which one arrived), so a single subscription per workspace is usually enough, and PATCH with is_active pauses and resumes it without a delete and a new secret.
• form_id limits a webhook to one form’s submission events. Every other event is workspace-wide, and a webhook with any of them refuses a form filter.
• filters limits deal events to deals in given pipelines or stages: { "pipeline_ids": [...], "stage_ids": [...] }, checked against where the deal is when the event happens (so deal.stage_changed is judged by the stage the deal moved to). Other events on the same webhook are not filtered. There are no field filters: subscribe to the specific event you need (deal.won rather than deal.updated) to keep deliveries down.
• The URL’s host is refused only when it points at a private or internal address. A host that does not resolve yet is accepted, so you can register a development endpoint before it is public; deliveries re-check the host every time. Localhost is never reachable from Orbit, so use a tunnel for local testing.
• A replayed create (same Idempotency-Key) returns the webhook without its secret. If the original response was lost before you stored the secret, delete that webhook and create it again under a new key.

​

Receiving deliveries

{
  "id": "5f0c1f2e-9c0a-5a3b-8d1e-6b2f0c9a4d11",
  "event": "contact.created",
  "object": "contact",
  "object_id": "7c1d2e3f-...",
  "team_id": "0c2b4d6e-...",
  "occurred_at": "2026-10-27T14:30:05.120Z",
  "timestamp": "2026-10-27T14:30:05.120Z",
  "actor": { "user_id": null, "app_id": null },
  "source": "app",
  "data": {
    "contact_id": "7c1d2e3f-...",
    "contact": { "id": "7c1d2e3f-...", "email": "jane@acme.com", "first_name": "Jane", "last_name": "Doe", "company": "Acme", "status": "active" }
  }
}

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(payload, 'utf8').digest('hex');
  return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

​

Delivery, retries and logs

• Submissions and meetings are delivered as they happen; CRM, call and submission-change events within about a minute.
• A failed delivery (timeout, connection error, 5xx or 429) is retried with exponential backoff, up to 3 retries by default. Retry-After on a 429 is honoured. Other 4xx responses are final.
• 10 consecutive failed events switch the webhook off. GET /api/v1/webhooks/:id shows is_active, consecutive_failures and last_error; PATCH with { "is_active": true } turns it back on.
• Deliveries are at-least-once. De-duplicate on id (also sent as X-Orbit-Event-ID); a retry carries the same one. Order is not guaranteed; use occurred_at.
• GET /api/v1/webhooks/:id/deliveries lists every attempt, with status codes and errors, for debugging a customer’s installation.

​

Best practices

​

Next steps