← Back to blog

Manage Outbound Webhooks by REST API: Create, Test, and Retry Deliveries

October 3, 2026 · Eric · 8 min read

Receiving a webhook is easy. Trusting one is not. The hard part is everything around the delivery: did the request actually go out, which attempt failed, why did the endpoint return a 500, and how do you rotate the signing secret without breaking your receiver?

Agent Media Tools exposes that whole lifecycle as a small REST surface — /api/user-webhooks — so you can register endpoints, fire a real test delivery, read the per-attempt delivery log, verify HMAC signatures, and rotate or disable a webhook without touching a dashboard. This guide walks the verified endpoints with curl and Python.

What this API manages (and what it doesn't)

There are two different webhook features on the platform, and mixing them up wastes time:

Outbound webhooks are registered against your account, not against a single agent key, and every route is session-authenticated. That is deliberate: only the human who owns the account should be able to change where notifications go or rotate a signing secret. An agent API key cannot rewrite its own notification targets.

Today, the create and update routes accept three subscription values — pipeline.started, pipeline.completed, and pipeline.failed. Pipeline runs emit pipeline.completed and pipeline.failed, so those are the two you will actually receive in practice.

Step 1 — Create a receiver you can inspect

Step 1

Before registering an outbound webhook, stand up something that records the exact request. The fastest option is a webhook inbox — create it once and you get a permanent URL plus a JSON view of everything it received.

curl -s -c cookies.txt -b cookies.txt \
  -X POST https://agentmediatools.com/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

# → {"success":true,"user":{"username":"you", ...}}

curl -s -c cookies.txt -b cookies.txt \
  -X POST https://agentmediatools.com/api/webhook-inbox \
  -H 'Content-Type: application/json' \
  -d '{"name":"pipeline-events"}'

The response contains the URL you will hand to the webhook engine:

{
  "success": true,
  "slug": "k7fq2m9x1a4d",
  "webhook_url": "https://agentmediatools.com/hook/k7fq2m9x1a4d",
  "list_url": "https://agentmediatools.com/hook/k7fq2m9x1a4d/inspect"
}

That webhook_url is public and accepts any HTTP method, so it works as a receiver for this walkthrough. When you are done testing, delete the inbox instead of leaving it lying around: DELETE /api/webhook-inbox/{slug}.

Step 2 — Register the outbound webhook

Registration takes a URL, an event list, an optional signing secret, and an optional retry budget. The URL is validated server-side: it must be http or https, must not contain credentials, and its hostname must resolve to a public address. Loopback and private-range targets are rejected at registration time, so a localhost receiver will fail here with a 400 rather than silently time out later.

curl -s -c cookies.txt -b cookies.txt \
  -X POST https://agentmediatools.com/api/user-webhooks \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "pipeline monitor",
    "url": "https://agentmediatools.com/hook/k7fq2m9x1a4d",
    "events": ["pipeline.completed", "pipeline.failed"],
    "secret": "whsec_choose_a_long_random_string",
    "max_retries": 3
  }'
{
  "success": true,
  "webhook": {
    "id": 12,
    "name": "pipeline monitor",
    "url": "https://agentmediatools.com/hook/k7fq2m9x1a4d",
    "events": ["pipeline.completed", "pipeline.failed"]
  }
}

Keep the id — every other call needs it. Two details worth knowing:

The signing secret is stored server-side and is never returned by the list endpoint, so record it in your own secret store when you create it.

List your webhooks with delivery stats

curl -s -c cookies.txt -b cookies.txt \
  https://agentmediatools.com/api/user-webhooks

Each entry includes is_active, max_retries, last_success_at, last_failure_at, and a delivery_stats object with total, successful, and failed counts. That one call is usually enough to answer "is this integration healthy?" without opening the log.

Step 3 — Fire a real test delivery

The test route sends an actual HTTP POST through the same delivery engine your production events use, so it exercises DNS resolution, TLS, timeouts, headers, and logging. It does not just validate the URL.

curl -s -c cookies.txt -b cookies.txt \
  -X POST https://agentmediatools.com/api/user-webhooks/12/test
{"success":true,"delivery_id":91,"message":"Test webhook sent"}

The test body is a normal pipeline.completed payload tagged as a test run:

{
  "event": "pipeline.completed",
  "timestamp": "2026-10-03T18:22:41.507Z",
  "data": {
    "pipeline_id": "test",
    "pipeline_name": "Test Event",
    "run_id": "test-1759515761507",
    "status": "completed",
    "step_count": 0,
    "duration_ms": 0
  }
}

Now read what the receiver actually saw, from the inbox side:

curl -s "https://agentmediatools.com/hook/k7fq2m9x1a4d/inspect?format=json"

You will see the headers the delivery engine sets on every outbound call:

{
  "inbox": { "name": "pipeline-events", "slug": "k7fq2m9x1a4d" },
  "payloads": [
    {
      "id": 33,
      "method": "POST",
      "headers": "{\"content-type\":\"application/json\",\"user-agent\":\"AgentMediaTools-Webhook/1.0\",\"x-webhook-event\":\"pipeline.completed\",\"x-webhook-delivery-id\":\"91\",\"x-webhook-signature\":\"sha256=5a1c...e9\"}",
      "body": "{\"event\":\"pipeline.completed\",\"timestamp\":\"2026-10-03T18:22:41.507Z\",\"data\":{...}}",
      "created_at": "2026-10-03 18:22:41"
    }
  ]
}

Note X-Webhook-Delivery-Id: it matches the log row you are about to query, which is how you connect "a call arrived at my server" with "the platform thinks this delivery succeeded".

Step 4 — Verify the signature instead of trusting the source

If you set a secret, every delivery carries X-Webhook-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body keyed by that secret. Verify against the raw bytes — re-serializing parsed JSON will change the body and break the comparison.

import hmac, hashlib

def verified(raw_body: bytes, header_signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    received = (header_signature or "").removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

With Flask or FastAPI, request the raw body before any JSON parser runs. Without a secret, deliveries still carry X-Webhook-Event and X-Webhook-Delivery-Id, but there is nothing to authenticate — treat the payload as unverified input and never act on it directly.

Step 5 — Read the delivery log

curl -s -c cookies.txt -b cookies.txt \
  "https://agentmediatools.com/api/user-webhooks/12/deliveries?limit=20"

Each row is one attempt, newest first (limit defaults to 50, caps at 200; combine with offset to page):

FieldWhat it tells you
eventWhich event name was delivered
success1 only when the receiver answered 2xx
status_codeNull when the connection itself failed
error_messageTimeout, DNS, or transport error text
attempt / max_attemptsWhich try this was, and the budget
duration_msRound-trip time of the POST
next_retry_atWhen the next attempt is scheduled, if any
delivered_atWhen the attempt finished

Response bodies are recorded to cap debugging trips, but they are not part of this log response — log the payload on your own side if you need to inspect what a broken handler returned.

Step 6 — Retries, timeouts, and manual replays

A delivery counts as successful only on a 2xx status. Anything else — a 500, a connection reset, or a response slower than 15 seconds — is a failure, and the engine schedules retries with exponential backoff: 30 seconds, then 2 minutes, then 5 minutes, up to your max_retries budget.

To force scheduled retries to run now:

curl -s -c cookies.txt -b cookies.txt \
  -X POST https://agentmediatools.com/api/user-webhooks/retry-all
{"success":true,"retried":2}

Be precise about what that call is: it triggers the delivery engine's due-retry sweep, so the count it returns covers every delivery that was due at that moment — not only the ones attached to your webhooks. Use it to unstick a backlog after you have fixed a broken receiver; do not treat the number as a per-account metric.

There is no per-delivery replay endpoint today. If a single event needs to be redelivered, fix the receiver and let the scheduled attempt run, or have your app trigger the pipeline again.

Step 7 — Rotate, pause, and delete

PUT /api/user-webhooks/12 is a partial update: send only what changes. That makes safe secret rotation a two-step deploy — add acceptance of the new secret to your receiver, then swap it on the platform.

# 1. Rotate the signing secret
curl -s -c cookies.txt -b cookies.txt \
  -X PUT https://agentmediatools.com/api/user-webhooks/12 \
  -H 'Content-Type: application/json' \
  -d '{"secret":"whsec_rotated_secret"}'

# 2. Pause without losing history or the URL
curl -s -c cookies.txt -b cookies.txt \
  -X PUT https://agentmediatools.com/api/user-webhooks/12 \
  -H 'Content-Type: application/json' \
  -d '{"is_active":false}'

# 3. Delete when you are really done
curl -s -c cookies.txt -b cookies.txt \
  -X DELETE https://agentmediatools.com/api/user-webhooks/12

Pausing sets is_active to 0 and stops deliveries while keeping the delivery log and the last_success_at history intact — the right move for maintenance windows. Deleting is heavier: it removes the webhook, clears its delivery rows, and detaches any URL watch that was pointing at it. Prefer pause unless you are retiring the integration.

The whole loop in Python

import requests

s = requests.Session()
s.post("https://agentmediatools.com/api/login",
       json={"username": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}).raise_for_status()

hook = s.post("https://agentmediatools.com/api/user-webhooks", json={
    "name": "pipeline monitor",
    "url": "https://agentmediatools.com/hook/k7fq2m9x1a4d",
    "events": ["pipeline.completed", "pipeline.failed"],
    "secret": "whsec_choose_a_long_random_string",
    "max_retries": 3,
}).json()
hook_id = hook["webhook"]["id"]

s.post(f"https://agentmediatools.com/api/user-webhooks/{hook_id}/test").raise_for_status()

log = s.get(f"https://agentmediatools.com/api/user-webhooks/{hook_id}/deliveries",
            params={"limit": 10}).json()
for row in log["deliveries"]:
    print(row["id"], row["event"], row["success"], row["status_code"], row["attempt"])

Wire that into a cron or a scheduled check and you have a lightweight health probe for your own integrations: if the newest rows stop being success: 1, something on your side broke before you noticed.

Honest boundaries

Pair this with the payload and event reference, and outbound webhooks stop being a black box: you can prove a delivery happened, prove who sent it, and recover from a broken receiver without deleting anything.

Try it in the Toolbox

Create an API key, build a pipeline, and point its completion events at your own endpoint.

Open toolbox