Webhooks · API reference

#List webhook events

GET/api/v1/webhooks/events

Operation list_webhook_events · needs scope webhooks:read

The events a subscription can receive.

bash

curl https://synconone.com/api/v1/webhooks/events \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": [
    {
      "name": "Emily Carter",
      "object": "string",
      "label": "string",
      "description": "Asked about annual terms on the website.",
      "emitted": true
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#List webhook subscriptions

GET/api/v1/webhooks

Operation list_webhooks · needs scope webhooks:read

Never includes a signing secret.

bash

curl https://synconone.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": [
    {
      "id": "pr_1a2b3c4d5e6f7a8b",
      "object": "string",
      "url": "https://example.com",
      "description": "Asked about annual terms on the website.",
      "events": [
        "string"
      ],
      "status": "active",
      "last_delivery_at": "2026-11-05T10:00:00Z",
      "last_error": "string",
      "created_at": "2026-11-05T10:00:00Z",
      "updated_at": "2026-11-05T10:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Subscribe a URL to events

POST/api/v1/webhooks

Operation create_webhook · needs scope webhooks:write

The response carries the signing secret once. Not idempotent on purpose: a replayed response would store the secret.

Body field	Type	Notes
`url` required	string	An https address (https is required in production). Private addresses are refused.
`events` required	list of record.created \| record.updated \| record.deleted \| opportunity.stage_changed \| opportunity.won \| opportunity.lost \| task.completed \| email.received \| meeting.analyzed \| forecast.snapshot_created	The events to receive, from GET /webhooks/events.
`description`	string

bash

curl -X POST https://synconone.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","events":["record.created"],"description":"Asked about annual terms on the website."}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "url": "https://example.com",
    "description": "Asked about annual terms on the website.",
    "events": [
      "string"
    ],
    "status": "active",
    "last_delivery_at": "2026-11-05T10:00:00Z",
    "last_error": "string",
    "created_at": "2026-11-05T10:00:00Z",
    "updated_at": "2026-11-05T10:00:00Z"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Get a webhook subscription

GET/api/v1/webhooks/{id}

Operation get_webhook · needs scope webhooks:read

Parameter	In	Type	Notes
`id` required	path	string	The subscription's id.

bash

curl https://synconone.com/api/v1/webhooks/pr_1a2b3c4d5e6f7a8b \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "url": "https://example.com",
    "description": "Asked about annual terms on the website.",
    "events": [
      "string"
    ],
    "status": "active",
    "last_delivery_at": "2026-11-05T10:00:00Z",
    "last_error": "string",
    "created_at": "2026-11-05T10:00:00Z",
    "updated_at": "2026-11-05T10:00:00Z"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Change a webhook subscription

PATCH/api/v1/webhooks/{id}

Operation update_webhook · needs scope webhooks:write

Only the keys sent are changed. A new url is checked the same way as on create.

Parameter	In	Type	Notes
`id` required	path	string	The subscription's id.

Body field	Type	Notes
`url`	string
`events`	list of record.created \| record.updated \| record.deleted \| opportunity.stage_changed \| opportunity.won \| opportunity.lost \| task.completed \| email.received \| meeting.analyzed \| forecast.snapshot_created
`description`	string
`status`	active \| disabled	Disabling stops deliveries and cancels the ones waiting.

bash

curl -X PATCH https://synconone.com/api/v1/webhooks/pr_1a2b3c4d5e6f7a8b \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","events":["record.created"],"description":"Asked about annual terms on the website.","status":"active"}'

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "url": "https://example.com",
    "description": "Asked about annual terms on the website.",
    "events": [
      "string"
    ],
    "status": "active",
    "last_delivery_at": "2026-11-05T10:00:00Z",
    "last_error": "string",
    "created_at": "2026-11-05T10:00:00Z",
    "updated_at": "2026-11-05T10:00:00Z"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 409: Conflict, approval required, or idempotent request in progress. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Unsubscribe

DELETE/api/v1/webhooks/{id}

Operation delete_webhook · needs scope webhooks:write

Deletes the subscription and its delivery history. This cannot be undone.

Parameter	In	Type	Notes
`id` required	path	string	The subscription's id.

bash

curl -X DELETE https://synconone.com/api/v1/webhooks/pr_1a2b3c4d5e6f7a8b \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "deleted": true
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#Replace the signing secret

POST/api/v1/webhooks/{id}/rotate-secret

Operation rotate_webhook_secret · needs scope webhooks:write

The old secret stops signing at once, with no overlap. The new one is returned once.

Parameter	In	Type	Notes
`id` required	path	string	The subscription's id.

bash

curl -X POST https://synconone.com/api/v1/webhooks/pr_1a2b3c4d5e6f7a8b/rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": {
    "id": "pr_1a2b3c4d5e6f7a8b",
    "object": "string",
    "url": "https://example.com",
    "description": "Asked about annual terms on the website.",
    "events": [
      "string"
    ],
    "status": "active",
    "last_delivery_at": "2026-11-05T10:00:00Z",
    "last_error": "string",
    "created_at": "2026-11-05T10:00:00Z",
    "updated_at": "2026-11-05T10:00:00Z"
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.

#List deliveries

GET/api/v1/webhooks/{id}/deliveries

Operation list_webhook_deliveries · needs scope webhooks:read

Newest first: what was sent, to where it got, and how it went.

Parameter	In	Type	Notes
`id` required	path	string	The subscription's id.
`limit`	query	integer	Page size, at most 100.
`cursor`	query	string

bash

curl https://synconone.com/api/v1/webhooks/pr_1a2b3c4d5e6f7a8b/deliveries \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

json

{
  "data": [
    {
      "id": "pr_1a2b3c4d5e6f7a8b",
      "object": "string",
      "event": "string",
      "event_id": "pr_1a2b3c4d5e6f7a8b",
      "status": "pending",
      "attempts": 1,
      "response_status": 1,
      "last_error": "string",
      "delivered_at": "2026-11-05T10:00:00Z",
      "next_attempt_at": "2026-11-05T10:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Errors: 401: Missing, invalid, revoked or expired API key. · 403: The key lacks the scope, or its role cannot do this. · 404: Not found, or not visible to this key. · 422: Validation failed. · 429: Rate limited. Honour Retry-After.. See errors.