Skip to main content

Add a Webhook Notification for Agent Run Completion

Yair Weinberger

Reindeer notifications send workspace events to an outbound webhook destination. The only supported notification event today is run_completion, which fires when an agent run completes.

A notification has two parts:

  • An HTTP connection profile, which defines the webhook URL and outbound authentication.
  • A notification rule, which subscribes the workspace to the run_completion event and points to that HTTP profile.

Before You Start

You need:

  • Editor access to the Reindeer workspace.
  • The destination webhook URL.
  • Any authentication material required by the receiving system, stored as Reindeer Secrets.
  • A decision on whether delivery should start enabled or paused.

Notification scope is currently workspace-wide. The notification applies to all agents in the workspace.

Add a Webhook Notification in the UI

  1. Open the workspace in Reindeer Console.
  2. Go to Settings > Access.
  3. Click New Profile.
  4. Select HTTP.
  5. Enter a display name, such as Run completion webhook.
  6. Set Base URL to the destination webhook endpoint.
  7. Configure outbound authentication if required:
    • auth: Basic, bearer token, or OAuth2 client credentials for the Authorization header.
    • api_key_header: a custom API key header such as x-api-key.
    • request_signing: HMAC signing for outbound webhook requests.
  8. Save the connection profile. Use Test if the destination supports the test request.
  9. Go to Settings > Notifications.
  10. Click New Notification.
  11. Enter a display name.
  12. Under Trigger, keep Agent run completed selected.
  13. Under Scope, use All agents in workspace.
  14. Under Delivery, select the HTTP connection profile.
  15. Leave Delivery enabled on, or turn it off to create the notification in a paused state.
  16. Click Create notification.

You can later pause delivery from the Notifications list without deleting the notification.

Add a Webhook Notification from the CLI and API

The current CLI supports creating the required secrets and HTTP connection profile. Notification creation is done through the Reindeer v1 Notifications API.

Set your workspace and profile:

PROFILE=prod
WORKSPACE=acme

reindeer login --profile "$PROFILE" --base-url https://api.<tenant>.reindeerlabs.ai

Create a secret if the webhook needs a bearer token:

reindeer -p "$PROFILE" -w "$WORKSPACE" secrets create \
  --name run-webhook-token \
  --description "Bearer token for run completion webhook" \
  --value "$WEBHOOK_BEARER_TOKEN" \
  --wait

Create the HTTP connection profile:

reindeer -p "$PROFILE" -w "$WORKSPACE" connection-profiles create --data '{
  "connection_profile_id": "run-webhook",
  "display_name": "Run completion webhook",
  "connection_profile_type": "http",
  "config": {
    "connection_profile_type": "http",
    "base_url": "https://webhooks.example.com/reindeer/run-completion",
    "auth": {
      "auth_type": "bearer",
      "secret_token": "workspaces/acme/secrets/run-webhook-token"
    }
  }
}'

For a custom API key header, add api_key_header to the HTTP profile config:

"api_key_header": {
  "header_name": "x-api-key",
  "secret_api_key": "workspaces/acme/secrets/run-webhook-api-key"
}

For HMAC request signing, add request_signing to the HTTP profile config:

"request_signing": {
  "secret_hmac_key": "workspaces/acme/secrets/run-webhook-hmac-key",
  "signature_header": "X-Signature",
  "algorithm": "sha256",
  "signature_encoding": "hex",
  "signature_prefix": "sha256="
}

Create the notification:

BASE_URL="$(reindeer -p "$PROFILE" config get base-url)"
TOKEN="$(jq -r --arg p "$PROFILE" '.profiles[$p].token.access_token' ~/.reindeer/config.json)"

curl -sS -X POST "$BASE_URL/api/v1/workspaces/$WORKSPACE/notifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_id": "run-completion-webhook",
    "display_name": "Run completion webhook",
    "events": ["run_completion"],
    "scope": { "type": "workspace" },
    "connection_profile": "run-webhook",
    "enabled": true
  }'

The API returns an operation. Poll it until done is true:

reindeer -p "$PROFILE" -w "$WORKSPACE" operations get <operation-id>

Update or Pause a Notification

To pause delivery without deleting the notification:

curl -sS -X PATCH "$BASE_URL/api/v1/workspaces/$WORKSPACE/notifications/run-completion-webhook" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

To resume delivery, set enabled to true.

Related Articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk