# Webhook API

Send HTTPS updates from services, scripts, and unattended workflows.

Send an HTTPS request from a script, service, or unattended workflow. Your workflow handles the work and scheduling; Agent Alerts handles the phone update.

## Create a publishing connection

Open [computer setup](/agent), choose publish-only access, then scan and approve the request in Agent Alerts on iPhone. Compare the code shown on both devices.

The website reveals the publishing token once after approval. Save it directly in your workflow's secret store as `AGENTALERTS_AGENT_TOKEN`. Keep it out of source code, URLs, logs, and chat.

## Send an update

Method: `POST`

Endpoint:

```text
https://www.andreas.ink/api/agent
```

Configure these headers through your automation tool's secret-variable picker:

```text
Authorization: Bearer <token from your secret store>
Content-Type: application/json
Idempotency-Key: first-test-001
```

Send this JSON body:

```json
{
  "title": "Webhook test",
  "summary": "Hello from my workflow.",
  "status": "good",
  "activity_id": "my-workflow",
  "source_name": "My workflow",
  "surfaces": ["live_activity", "notification"],
  "idempotency_key": "first-test-001"
}
```

Use non-sensitive content for the first test and confirm the result on your iPhone. Lock Screen content can be visible to people near the device.

## IDs and retries

Keep `activity_id` stable for updates about the same subject. Assign each new event a new `idempotency_key`, matching the header and body. Reuse a key only to retry that exact event with the same payload.

A stable activity ID identifies the surface to update. An idempotency key identifies one send event. They serve different purposes.

## Interpret the response

- HTTP `401` means authentication failed. Do not report success from a success-looking body after a failed HTTP status.
- `no_targets` means the account has no registered target for the requested surface.
- `quota_limited` means the original alert was suppressed by the account's delivered-alert limit. Check `original_alert_delivered` and `retryable`; do not retry a non-retryable quota result or call it delivered.
- An accepted request or APNs acceptance does not establish visible iPhone delivery. Confirm the phone result during setup.

Free accounts have 350 delivered-alert events per UTC day. Pro accounts, including lifetime Pro, have 3,500. A send to multiple alert surfaces counts once; widget-only refreshes do not consume that delivered-alert allowance. See [pricing](/agent-alerts/pricing) for the published plans.

## Responses and credentials

Publish-only credentials send updates. Interactive responses require Pro and appropriate access on the originating connection. See [responses and permissions](/agent-alerts/docs/responses-and-permissions) before building an approval workflow.


Source: https://www.andreas.ink/agent-alerts/docs/webhook-api
