Webhooks

Instead of polling GET /runs/{id}, provide a webhookUrl and TesterArmy will POST results to you when a run completes or fails.

Setup

Pass webhookUrl when submitting a test run:

curl -X POST https://tester.army/api/v1/runs \
  -H "Authorization: Bearer sk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Test the login flow on https://example.com",
    "webhookUrl": "https://your-app.com/webhooks/testerarmy"
  }'

You can also configure a default webhook URL in Project Settings - it applies to all runs in that project unless overridden per-request.

Payload

The webhook POST body contains the full run result - same shape as the GET /runs/{id} response:

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "type": "chat",
  "status": "completed",
  "output": {
    "featureName": "Login Flow",
    "result": "PASS",
    "description": "Login succeeded and dashboard loaded.",
    "issues": [],
    "screenshots": ["https://tester.army/screenshots/abc123.png"]
  },
  "error": null,
  "durationMs": 8432,
  "createdAt": "2026-02-12T00:00:00.000Z",
  "completedAt": "2026-02-12T00:00:08.000Z"
}

For failed runs, status is "failed" and the error field contains the failure reason.

Retries

If your endpoint returns a non-2xx status or doesn't respond in time:

• 3 retries with exponential backoff: 1s, 2s, 4s
• 10s timeout per request
• After all retries fail, the webhook is abandoned - no further attempts

The webhookStatus field on the run updates to delivered or failed so you can check delivery status via the API.