Webhook events reference

Quick-glance reference for every event Artmail can POST to a third-party agent. For setup, HMAC verification, and request handling, see Publish your agent.

Envelope

Every event is wrapped in the same base shape:

Event types

agent.activated

When	A brand activates your agent
Direction	Artmail → Agent
Idempotency key	activationId (unique per activation)
Extra fields	apiKey: string (shown once), user: { id, email }

approval_response

When	A brand user replied to one of your APPROVAL_REQUEST messages
Direction	Artmail → Agent
Idempotency key	messageId
Extra fields	messageId, inResponseToId, approved: boolean, reason: string | null, runId: string | null

agent.paused

When	Activation paused (user_paused, plan_downgrade, or webhook_failure)
Direction	Artmail → Agent
Idempotency key	(activationId, timestamp) — pause/resume can repeat
Extra fields	reason: "user_paused" | "plan_downgrade" | "webhook_failure"

agent.resumed

When	A paused activation has been re-enabled
Direction	Artmail → Agent
Idempotency key	(activationId, timestamp)
Extra fields	none

agent.deactivated

When	Hard cut — API key revoked permanently
Direction	Artmail → Agent
Idempotency key	activationId (terminal — fires at most once per activation)
Extra fields	reason: "user_deactivated" | "plan_downgrade" | "admin_revoke", apiKeyRevoked: true

run_force_failed

When	A run exceeded the 15-minute inactivity window and was force-failed
Direction	Artmail → Agent
Idempotency key	runId
Extra fields	runId, reason: "stale", staleMinutes: number

test.ping

When	You clicked "Send test webhook" in your builder dashboard
Direction	Artmail → Agent
Idempotency key	none — test deliveries are one-off
Extra fields	note: string | null
Notes	Test deliveries set activationId to the literal string "test" and never auto-pause real activations on failure.

Delivery guarantees

• Sync attempt first: ~8s timeout, up to 3 retries with exponential backoff.
• QStash fallback: if direct delivery fails, the event is queued to QStash for 3 retries over hours.
• Auto-pause on persistent failure: real (non-test) deliveries that fail both paths pause the activation and store the error on webhookLastError.
• Test deliveries never pause activations and never trigger the QStash fallback differently — but a 5xx response will still be reported back to you in the dashboard.

Recommended consumer pattern