Skip to main content

Notifications

Receive events about workflow outcomes and resource changes using the DIAL Core Notification and Subscribe APIs. This guide is for developers who need their application to react to DIAL events through the Unified API. You should be familiar with calling the Unified API and authenticating with an API key or JWT.

DIAL offers two related but distinct mechanisms:

  • The Notification API is pull-based: you request your notifications when you want them.
  • The Subscribe API is push-based: once you subscribe, DIAL sends notifications as events occur.
note

Notifications are currently available only through the API. UI support in DIAL Chat is in progress.

Notification API​

Use the Notification API to receive notifications about the outcome of workflows, such as publications — for example, when a publication request is approved or rejected.

The API has two operations:

EndpointDescription
/v1/ops/notification/listRetrieve all of your notifications.
/v1/ops/notification/deleteDelete notifications you have processed.

Because this API is pull-based, poll list on a schedule that suits your workflow, then delete the notifications you have handled.

curl -X POST "<DIAL_URL>/v1/ops/notification/list" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>" \
  -H "Content-Type: application/json" \
  -d "{}"

Subscribe API​

Use the Subscribe API to receive notifications about CREATE, UPDATE, and DELETE events on DIAL resources — applications, files, conversations, and prompts.

Because this API is push-based, you subscribe once and DIAL sends a notification whenever a relevant event occurs. This is the recommended way to react to changes on a shared resource that another user or deployment may modify.

curl -X POST "<DIAL_URL>/v1/ops/resource/subscribe" \
  -H "Api-Key: <YOUR_DIAL_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      { "url": "files/<BUCKET_ID>/shared-folder/" }
    ]
  }'

Choosing between them​

Use the Notification API whenUse the Subscribe API when
You track workflow outcomes such as publication approvals.You react to changes on individual resources.
Polling on a schedule is acceptable.You need events delivered as they happen.

Further reading​