SalesOS

Webhooks

Webhook subscription management

Get all webhooks for current user

GET
/v1/webhooks

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

isActiveboolean
curl -X GET "https://api.salesos.org/v1/webhooks?isActive=true" \
  -H "Authorization: Bearer <token>"

WebhookViewArray

[
  {
    "id": "string",
    "userId": "string",
    "organizationId": "string",
    "name": "string",
    "description": "string",
    "url": "string",
    "events": [
      "string"
    ],
    "isActive": true,
    "retryEnabled": true,
    "maxRetries": 0,
    "retryDelaySeconds": 0,
    "customHeaders": null,
    "deliveryCount": 0,
    "successCount": 0,
    "failureCount": 0,
    "consecutiveFailures": 0,
    "lastDeliveryAt": "2019-08-24T14:15:22Z",
    "lastSuccessAt": "2019-08-24T14:15:22Z",
    "lastFailureAt": "2019-08-24T14:15:22Z",
    "autoDisableThreshold": 0,
    "disabledReason": "string",
    "disabledAt": "2019-08-24T14:15:22Z",
    "payloadVersion": 0,
    "namedCredentialId": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "status": "ACTIVE",
    "totalDeliveries": 0,
    "successfulDeliveries": 0,
    "managedBy": {
      "installationId": "string",
      "componentId": "string",
      "appId": "string",
      "appName": "string",
      "appSlug": "string"
    }
  }
]

Create a new webhook

POST
/v1/webhooks

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
nameRequiredstring

Webhook name

descriptionstring

Webhook description

urlRequiredstring

Webhook endpoint URL

Format: "uri"
eventsRequiredarray<string>

Events to subscribe to

headersobject

Custom headers to send with requests

isActiveboolean

Is webhook active

Default: true
retryAttemptsnumber

Number of retry attempts on failure

Default: 3Minimum: 0Maximum: 10
retryDelaySecondsnumber

Delay between retries in seconds

Default: 60Minimum: 10Maximum: 3600
payloadVersionnumber

Payload format: 2 = versioned envelope {id,type,version,occurredAt,organizationId,data}; 1 = legacy {event,eventId,timestamp,data}

Default: 2Value in: 1 | 2
secretstring

Signing secret (16–128 chars). Generated (whsec_…) when omitted.

Minimum length: 16Maximum length: 128
namedCredentialIdstring

Named credential whose auth is added to every delivery; the URL must sit under its base URL. Empty string clears it.

curl -X POST "https://api.salesos.org/v1/webhooks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "url": "http://example.com",
    "events": [
      "lead.created",
      "opportunity.won"
    ],
    "headers": {
      "property1": "string",
      "property2": "string"
    },
    "isActive": true,
    "retryAttempts": 3,
    "retryDelaySeconds": 60,
    "payloadVersion": 1,
    "secret": "stringstringstri",
    "namedCredentialId": "string"
  }'

WebhookWithSecret

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "isActive": true,
  "retryEnabled": true,
  "maxRetries": 0,
  "retryDelaySeconds": 0,
  "customHeaders": null,
  "deliveryCount": 0,
  "successCount": 0,
  "failureCount": 0,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2019-08-24T14:15:22Z",
  "lastSuccessAt": "2019-08-24T14:15:22Z",
  "lastFailureAt": "2019-08-24T14:15:22Z",
  "autoDisableThreshold": 0,
  "disabledReason": "string",
  "disabledAt": "2019-08-24T14:15:22Z",
  "payloadVersion": 0,
  "namedCredentialId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "totalDeliveries": 0,
  "successfulDeliveries": 0,
  "managedBy": {
    "installationId": "string",
    "componentId": "string",
    "appId": "string",
    "appName": "string",
    "appSlug": "string"
  },
  "secret": "string"
}

Get list of available webhook events

GET
/v1/webhooks/events

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/webhooks/events" \
  -H "Authorization: Bearer <token>"

[
  "string"
]

Get webhook statistics

GET
/v1/webhooks/stats

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/webhooks/stats" \
  -H "Authorization: Bearer <token>"

Get a webhook by ID

GET
/v1/webhooks/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X GET "https://api.salesos.org/v1/webhooks/<string>" \
  -H "Authorization: Bearer <token>"

WebhookWithSecret

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "isActive": true,
  "retryEnabled": true,
  "maxRetries": 0,
  "retryDelaySeconds": 0,
  "customHeaders": null,
  "deliveryCount": 0,
  "successCount": 0,
  "failureCount": 0,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2019-08-24T14:15:22Z",
  "lastSuccessAt": "2019-08-24T14:15:22Z",
  "lastFailureAt": "2019-08-24T14:15:22Z",
  "autoDisableThreshold": 0,
  "disabledReason": "string",
  "disabledAt": "2019-08-24T14:15:22Z",
  "payloadVersion": 0,
  "namedCredentialId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "totalDeliveries": 0,
  "successfulDeliveries": 0,
  "managedBy": {
    "installationId": "string",
    "componentId": "string",
    "appId": "string",
    "appName": "string",
    "appSlug": "string"
  },
  "secret": "string"
}

Update a webhook

PATCH
/v1/webhooks/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
namestring

Webhook name

descriptionstring

Webhook description

urlstring

Webhook endpoint URL

Format: "uri"
eventsarray<string>

Events to subscribe to

headersobject

Custom headers to send with requests

isActiveboolean

Is webhook active

retryAttemptsnumber

Number of retry attempts on failure

Minimum: 0Maximum: 10
retryDelaySecondsnumber

Delay between retries in seconds

Minimum: 10Maximum: 3600
payloadVersionnumber

Payload format: 2 = versioned envelope {id,type,version,occurredAt,organizationId,data}; 1 = legacy {event,eventId,timestamp,data}

Default: 2Value in: 1 | 2
namedCredentialIdstring

Named credential whose auth is added to every delivery; the URL must sit under its base URL. Empty string clears it.

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X PATCH "https://api.salesos.org/v1/webhooks/<string>" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "url": "http://example.com",
    "events": [
      "string"
    ],
    "headers": {
      "property1": "string",
      "property2": "string"
    },
    "isActive": true,
    "retryAttempts": 10,
    "retryDelaySeconds": 10,
    "payloadVersion": 1,
    "namedCredentialId": "string"
  }'

WebhookView

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "isActive": true,
  "retryEnabled": true,
  "maxRetries": 0,
  "retryDelaySeconds": 0,
  "customHeaders": null,
  "deliveryCount": 0,
  "successCount": 0,
  "failureCount": 0,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2019-08-24T14:15:22Z",
  "lastSuccessAt": "2019-08-24T14:15:22Z",
  "lastFailureAt": "2019-08-24T14:15:22Z",
  "autoDisableThreshold": 0,
  "disabledReason": "string",
  "disabledAt": "2019-08-24T14:15:22Z",
  "payloadVersion": 0,
  "namedCredentialId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "totalDeliveries": 0,
  "successfulDeliveries": 0,
  "managedBy": {
    "installationId": "string",
    "componentId": "string",
    "appId": "string",
    "appName": "string",
    "appSlug": "string"
  }
}

Delete a webhook

DELETE
/v1/webhooks/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X DELETE "https://api.salesos.org/v1/webhooks/<string>" \
  -H "Authorization: Bearer <token>"

SuccessResponse

{
  "success": true
}

Activate a webhook

POST
/v1/webhooks/{id}/activate

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/webhooks/<string>/activate" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

WebhookView

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "isActive": true,
  "retryEnabled": true,
  "maxRetries": 0,
  "retryDelaySeconds": 0,
  "customHeaders": null,
  "deliveryCount": 0,
  "successCount": 0,
  "failureCount": 0,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2019-08-24T14:15:22Z",
  "lastSuccessAt": "2019-08-24T14:15:22Z",
  "lastFailureAt": "2019-08-24T14:15:22Z",
  "autoDisableThreshold": 0,
  "disabledReason": "string",
  "disabledAt": "2019-08-24T14:15:22Z",
  "payloadVersion": 0,
  "namedCredentialId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "totalDeliveries": 0,
  "successfulDeliveries": 0,
  "managedBy": {
    "installationId": "string",
    "componentId": "string",
    "appId": "string",
    "appName": "string",
    "appSlug": "string"
  }
}

Deactivate a webhook

POST
/v1/webhooks/{id}/deactivate

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/webhooks/<string>/deactivate" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

WebhookView

{
  "id": "string",
  "userId": "string",
  "organizationId": "string",
  "name": "string",
  "description": "string",
  "url": "string",
  "events": [
    "string"
  ],
  "isActive": true,
  "retryEnabled": true,
  "maxRetries": 0,
  "retryDelaySeconds": 0,
  "customHeaders": null,
  "deliveryCount": 0,
  "successCount": 0,
  "failureCount": 0,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2019-08-24T14:15:22Z",
  "lastSuccessAt": "2019-08-24T14:15:22Z",
  "lastFailureAt": "2019-08-24T14:15:22Z",
  "autoDisableThreshold": 0,
  "disabledReason": "string",
  "disabledAt": "2019-08-24T14:15:22Z",
  "payloadVersion": 0,
  "namedCredentialId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "status": "ACTIVE",
  "totalDeliveries": 0,
  "successfulDeliveries": 0,
  "managedBy": {
    "installationId": "string",
    "componentId": "string",
    "appId": "string",
    "appName": "string",
    "appSlug": "string"
  }
}

Regenerate webhook secret

POST
/v1/webhooks/{id}/regenerate-secret

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X POST "https://api.salesos.org/v1/webhooks/<string>/regenerate-secret" \
  -H "Authorization: Bearer <token>"

WebhookSecretRotated

{
  "id": "string",
  "secret": "string",
  "message": "string"
}

Send a test event (the catalog sample for `type`)

POST
/v1/webhooks/{id}/test

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
typestring

Catalog event type whose sample payload is sent (defaults to the first subscribed event)

eventDeprecatedstring

Older clients sent event.

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/webhooks/<string>/test" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "opportunity.stage_changed",
    "event": "string"
  }'

WebhookTestResult

{
  "success": true,
  "message": "string",
  "deliveryId": "string",
  "eventId": "string",
  "type": "string",
  "statusCode": 0,
  "responseStatus": 0,
  "responseTime": 0,
  "responseBody": "string",
  "error": "string",
  "errorMessage": "string"
}

Delivery attempts, newest first (paged)

GET
/v1/webhooks/{id}/deliveries

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Query Parameters

successboolean
statusstring
Value in: "SUCCEEDED" | "RETRYING" | "FAILED"
eventstring
eventIdstring
pagenumber
limitnumber
curl -X GET "https://api.salesos.org/v1/webhooks/<string>/deliveries?success=true&status=SUCCEEDED&event=%3Cstring%3E&eventId=%3Cstring%3E&page=0&limit=0" \
  -H "Authorization: Bearer <token>"

WebhookDeliveryPage

{
  "data": [
    {
      "id": "string",
      "webhookId": "string",
      "event": "string",
      "eventId": "string",
      "requestPayload": null,
      "requestHeaders": null,
      "statusCode": 0,
      "responseBody": "string",
      "responseTimeMs": 0,
      "success": true,
      "errorMessage": "string",
      "attemptNumber": 0,
      "nextRetryAt": "2019-08-24T14:15:22Z",
      "organizationId": "string",
      "eventVersion": 0,
      "source": "string",
      "replayOfId": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "status": "SUCCEEDED"
    }
  ],
  "total": 0,
  "page": 0,
  "limit": 0,
  "totalPages": 0,
  "logs": [
    {
      "id": "string",
      "webhookId": "string",
      "event": "string",
      "eventId": "string",
      "requestPayload": null,
      "requestHeaders": null,
      "statusCode": 0,
      "responseBody": "string",
      "responseTimeMs": 0,
      "success": true,
      "errorMessage": "string",
      "attemptNumber": 0,
      "nextRetryAt": "2019-08-24T14:15:22Z",
      "organizationId": "string",
      "eventVersion": 0,
      "source": "string",
      "replayOfId": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "status": "SUCCEEDED"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "totalPages": 0
  }
}

One delivery attempt: request headers and body, response

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

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
deliveryIdRequiredstring
curl -X GET "https://api.salesos.org/v1/webhooks/<string>/deliveries/<string>" \
  -H "Authorization: Bearer <token>"

WebhookDelivery

{
  "id": "string",
  "webhookId": "string",
  "event": "string",
  "eventId": "string",
  "requestPayload": null,
  "requestHeaders": null,
  "statusCode": 0,
  "responseBody": "string",
  "responseTimeMs": 0,
  "success": true,
  "errorMessage": "string",
  "attemptNumber": 0,
  "nextRetryAt": "2019-08-24T14:15:22Z",
  "organizationId": "string",
  "eventVersion": 0,
  "source": "string",
  "replayOfId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "status": "SUCCEEDED"
}

Re-send a delivery with the same event id (receivers can dedupe)

POST
/v1/webhooks/{id}/deliveries/{deliveryId}/replay

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
deliveryIdRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/webhooks/<string>/deliveries/<string>/replay" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

WebhookDelivery

{
  "id": "string",
  "webhookId": "string",
  "event": "string",
  "eventId": "string",
  "requestPayload": null,
  "requestHeaders": null,
  "statusCode": 0,
  "responseBody": "string",
  "responseTimeMs": 0,
  "success": true,
  "errorMessage": "string",
  "attemptNumber": 0,
  "nextRetryAt": "2019-08-24T14:15:22Z",
  "organizationId": "string",
  "eventVersion": 0,
  "source": "string",
  "replayOfId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "status": "SUCCEEDED"
}

Stream live catalog events as Server-Sent Events (text/event-stream); each `event` frame is the webhook envelope body

POST
/v1/webhooks/listen

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
eventsarray<string>

Catalog event types to stream (e.g. lead.created, opportunity.*); all when omitted Items: at most 64.

curl -X POST "https://api.salesos.org/v1/webhooks/listen" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "string"
    ]
  }'

text/event-stream: ready, then event frames (data = webhook envelope JSON), dropped, end

"string"

Send an event type's catalog sample (test: true) to this org's listen sessions only

POST
/v1/webhooks/listen/trigger

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
typeRequiredstring

Catalog event type; its catalog sample is sent, flagged test: true

Maximum length: 80

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/webhooks/listen/trigger" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lead.created"
  }'

{
  "eventId": "string",
  "type": "string",
  "delivered": 0
}

Payments

Payment processing and billing

Events

Catalog of webhook event types and their JSON Schemas; your organization's custom events: catalog and publish