Interactive Notifications

Overview

Interactive notifications display a message with clickable buttons. Users respond directly in Slack or Teams, and you can track responses via polling or callbacks. Common use cases:

Deployment approvals
Incident acknowledgement
Shift confirmations
Survey questions

Endpoint

POST /api/notify

Request body

Include the response_request field alongside the standard notification fields.

string[]

required

Recipients. Maximum 50.

string

required

The prompt shown above the buttons. Maximum 4000 characters.

string

Your correlation ID. Maximum 200 characters.

object

required

Configures the interactive behavior.

Show response_request fields

array

required

2 to 5 response buttons.Each option has:

text (string, 1-75 chars) — Button label shown to the user
value (string, 1-100 chars) — Machine-readable value returned in responses

number

required

Minutes before the request expires. Range: 1-1440 (24 hours).After expiry, unresponded users are marked as expired and buttons are disabled.

string

default:"onUserAction"

When to disable buttons for a given user:

onUserAction — Buttons are disabled immediately after the user clicks. The request completes when all users have responded or the timeout is reached.
onTimeout — Buttons remain active until timeout. Users can change their response. Final values are captured at expiry.

string

HTTPS URL to receive a POST with the final results when the request completes.Must be publicly reachable. Validated on submission (DNS resolution, HTTPS required, no private IPs). See Callbacks.

Response

string

"ok" on success.

string

Unique identifier for this notification request. Use it to check status.

string

Only present when callback_url is provided. Use this to verify callback signatures. Store it securely — it is only returned once.

{
  "status": "ok",
  "request_id": "req_a1b2c3d4e5f6...",
  "callback_secret": "dGhpc19pc19hX3NlY3JldA..."
}

Example: deployment approval

curl -X POST https://app.nextks.com/api/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "user_emails": ["lead@company.com"],
    "message": "Release v2.4.1 is ready.\nChanges: 3 bug fixes, 1 new feature.\n\nDeploy to production?",
    "external_reference_id": "deploy-v2.4.1",
    "response_request": {
      "options": [
        { "text": "Approve", "value": "approve" },
        { "text": "Reject", "value": "reject" },
        { "text": "Delay 1h", "value": "delay" }
      ],
      "timeout_minutes": 60,
      "callback_url": "https://ci.company.com/hooks/nextks"
    }
  }'

const response = await fetch('https://app.nextks.com/api/notify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    user_emails: ['lead@company.com'],
    message: 'Release v2.4.1 is ready.\nChanges: 3 bug fixes, 1 new feature.\n\nDeploy to production?',
    external_reference_id: 'deploy-v2.4.1',
    response_request: {
      options: [
        { text: 'Approve', value: 'approve' },
        { text: 'Reject', value: 'reject' },
        { text: 'Delay 1h', value: 'delay' },
      ],
      timeout_minutes: 60,
      callback_url: 'https://ci.company.com/hooks/nextks',
    },
  }),
})

const data = await response.json()
// Store the callback_secret to verify incoming callbacks
console.log(data.request_id)       // "req_a1b2c3d4e5f6..."
console.log(data.callback_secret)  // "dGhpc19pc19hX3NlY3JldA..."

import requests

response = requests.post(
    "https://app.nextks.com/api/notify",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
    },
    json={
        "user_emails": ["lead@company.com"],
        "message": "Release v2.4.1 is ready.\nChanges: 3 bug fixes, 1 new feature.\n\nDeploy to production?",
        "external_reference_id": "deploy-v2.4.1",
        "response_request": {
            "options": [
                {"text": "Approve", "value": "approve"},
                {"text": "Reject", "value": "reject"},
                {"text": "Delay 1h", "value": "delay"},
            ],
            "timeout_minutes": 60,
            "callback_url": "https://ci.company.com/hooks/nextks",
        },
    },
)

data = response.json()
# Store the callback_secret to verify incoming callbacks
print(data["request_id"])       # "req_a1b2c3d4e5f6..."
print(data["callback_secret"])  # "dGhpc19pc19hX3NlY3JldA..."

Message appearance

The notification renders as:

Message text — Your message content with markdown formatting
Response buttons — One button per option
Footer — Shows validity period and sender name (e.g., “Valid for 1h. Sent by Alice via Notifications API.”)

After a user responds (in onUserAction mode), the message is updated to show their choice and the buttons are removed.

Disable modes

onUserAction (default)
onTimeout

Buttons disable immediately when the user clicks
The user’s choice is final
Request completes when all users respond or timeout is reached
Best for: approvals, acknowledgements — one-shot decisions

​Overview

​Endpoint

​Request body

​Response

​Example: deployment approval

​Message appearance

​Disable modes

Overview

Endpoint

Request body

Response

Example: deployment approval

Message appearance

Disable modes