Events

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

Event catalog: every webhook event type with its JSON Schema

curl -X GET "https://api.salesos.org/v1/events/catalog"

One event type (e.g. opportunity.stage_changed)

Path Parameters

typeRequiredstring

curl -X GET "https://api.salesos.org/v1/events/catalog/<string>"

{}

The event catalog plus this organization's custom event types

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/events/org-catalog" \
  -H "Authorization: Bearer <token>"

OrgEventCatalog

{
  "catalogVersion": 0,
  "envelope": {},
  "signature": {},
  "events": [
    {}
  ],
  "custom": [
    {
      "type": "custom.order_shipped",
      "version": 0,
      "category": "custom",
      "label": "string",
      "description": "string",
      "schema": {},
      "isActive": true,
      "publishAccess": "ADMINS"
    }
  ]
}

Publish a custom event (custom.<apiName>); the payload is validated against its schema

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

payloadRequiredobject

The event's data; validated against the type's current schema

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/events/custom/<string>" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "orderId": "SO-1042",
      "carrier": "UPS"
    }
  }'

PublishedCustomEvent

{
  "eventId": "evt_3f9c2a7d1b8e4c60a5d2f1e0b9c8a7d6",
  "type": "custom.order_shipped",
  "version": 0,
  "occurredAt": "2019-08-24T14:15:22Z",
  "webhooks": 0
}

Response

TypeScript

Response

TypeScript

Response

TypeScript