Skip to main content
POST
/
v1
/
widget
/
sessions
/
{sessionId}
/
push
Push subscribe
curl --request POST \
  --url https://api.example.com/v1/widget/sessions/{sessionId}/push \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    {}
  ],
  "secret": "<string>"
}
'

​
Overview

Roadmap — not yet available. The embeddable widget is a future feature.
Registers an HTTPS endpoint to receive push notifications for events in a widget session. Useful for server-side integrations where maintaining an SSE connection is not practical. Authentication: Widget session token.

​
Request headers

​
Authorization
string
required
Widget session token. Format: Bearer <sessionToken>. Obtain from Create widget session.

​
Path parameters

​
sessionId
string
required
The widget session identifier.

​
Request body

​
url
string
required
Your HTTPS endpoint to receive push notifications. Must be publicly reachable.
​
events
array
required
List of event types to subscribe to. One or more of: message.complete, session.expiry_warning.
​
secret
string
Optional signing secret. If provided, push payloads include an X-Widget-Signature: sha256=<hmac> header for verification.

​
Response

Returns 201 Created. 
{
  "subscriptionId": "wsub_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "sessionId": "wsess_01HX9VTPQR3KF8MZWBYD5N6JCE",
  "url": "https://your-service.example.com/widget-events",
  "events": ["message.complete"],
  "createdAt": "2024-04-01T14:30:00Z"
}

​
Error responses

StatusError codeDescription
400validation_errorurl not HTTPS or events empty
401unauthorizedMissing or invalid session token
404session_not_foundSession does not exist or has expired

​
Examples

curl https://api.causeflow.ai/v1/widget/sessions/wsess_01HX9VTPQR3KF8MZWBYD5N6JCE/push \
  -X POST \
  -H "Authorization: Bearer wst_live_EXAMPLE_TOKEN_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-service.example.com/widget-events",
    "events": ["message.complete"],
    "secret": "your-signing-secret"
  }'

Widget stream

Alternative: receive events via SSE

Close session

End the session when finished