Skip to main content

​
Create a webhook subscription

POST /api/v1/sites/{siteId}/outreach/webhooks Create a webhook subscription so Sight AI POSTs outreach events to your endpoint. Used by app integrations after the OAuth flow completes — your app gets an access token, then calls this endpoint to register its webhook URL and choose which events to receive.

​
Required headers

HeaderRequiredDescription
AuthorizationYesBearer sai_<64hex> (API key) OR Bearer sai_oauth_* (OAuth access token). See Authentication.
Content-TypeYesapplication/json.

​
Request body

FieldTypeRequiredDescription
labelstringYesA name for your reference (max 120 chars).
urlstringYesThe HTTPS URL Sight AI POSTs events to (max 2000 chars).
eventTypesstring[]YesThe subset of events to receive. Must be non-empty; each value must be in the event catalog.

​
Response

​
201 Created

{
  "subscription": {
    "id": "sub_abc123",
    "team_id": "team_xyz",
    "site_id": "site_abc123",
    "label": "CRM — inbound handler",
    "url": "https://your-app.com/webhooks/sightai",
    "secret_prefix": "sightai_wh_abc…",
    "event_types": ["outreach.reply_sent", "outreach.conversation_status_changed"],
    "is_active": true,
    "consecutive_failures": 0,
    "created_by_oauth_client_id": "sightai_client123",
    "created_at": "2026-06-29T12:00:00Z",
    "updated_at": "2026-06-29T12:00:00Z",
    "last_delivery_at": null,
    "last_delivery_status": null
  },
  "secret": "sightai_wh_<full-secret-shown-once>"
}
The secret is the HMAC signing secret. Copy it now — it’s never shown again. You’ll use it to verify the SightAI-Signature header on incoming webhooks. The subscription object returned (and all subsequent reads) only includes secret_prefix, never the full secret. When the caller is an OAuth token, created_by_oauth_client_id is stamped with the owning client so revoking that client cascades to delete this subscription. For API-key callers, it’s null.

​
Error responses

StatusCodeMeaning
400VALIDATION_ERRORInvalid body (bad URL, empty eventTypes, unknown event type)
401UNAUTHORIZEDMissing or invalid credentials
403INSUFFICIENT_SCOPECredentials lack webhooks:write
403SITE_NOT_LICENSEDSite does not have an active license
404SITE_NOT_FOUNDSite doesn’t exist or isn’t owned by the credential’s team

​
Example

curl -X POST https://app.trysight.ai/api/v1/sites/site_abc123/outreach/webhooks \
  -H "Authorization: Bearer sai_oauth_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "CRM — inbound handler",
    "url": "https://your-app.com/webhooks/sightai",
    "eventTypes": ["outreach.reply_sent", "outreach.conversation_status_changed", "outreach.contact_suppressed"]
  }'

​
List webhook subscriptions

GET /api/v1/sites/{siteId}/outreach/webhooks List all webhook subscriptions for a site. Returns the safe shape (no plaintext secrets).

​
Response

{
  "subscriptions": [
    {
      "id": "sub_abc123",
      "label": "CRM — inbound handler",
      "url": "https://your-app.com/webhooks/sightai",
      "secret_prefix": "sightai_wh_abc…",
      "event_types": ["outreach.reply_sent"],
      "is_active": true,
      "consecutive_failures": 0,
      "created_by_oauth_client_id": "sightai_client123",
      "created_at": "2026-06-29T12:00:00Z",
      "last_delivery_at": "2026-06-29T12:05:00Z",
      "last_delivery_status": "ok"
    }
  ]
}
Requires the webhooks:read scope.

​
Delete a webhook subscription

DELETE /api/v1/sites/{siteId}/outreach/webhooks/{id} Delete a webhook subscription. The subscription’s delivery history is cascaded (deleted automatically). Requires the webhooks:write scope.

​
Response

{ "success": true }
Returns 404 NOT_FOUND if the subscription doesn’t exist or doesn’t belong to the site.

​
Revoking an app’s access

To revoke an app integration’s access entirely (all its subscriptions + tokens), delete its OAuth client in Integrations → Sight AI API → OAuth apps. This cascades to delete every webhook subscription that client created and revokes its outstanding access/refresh tokens. See Webhooks for the full OAuth flow.
Subscription management is API-only — there is no dashboard form. The only dashboard surface for revoking a platform’s webhooks is deleting its OAuth client.