Send a test event
Sends a webhook.test event to this endpoint only (also while it is switched off), signed like every delivery, and waits up to 12 seconds for the answer. With type, it sends a made-up sample of that event type instead (sample ids, no real data), so a receiver can be tried with every shape. Either way the body carries test: true. One attempt, no retries, and it never counts toward switching the endpoint off (a 410 answer still does). 10 per minute per project.
POST
/v1/webhooks/{id}/testRequest
| Method and path | POST/v1/webhooks/{id}/test |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
| Rate limit | Yes. See Rate limits for the numbers and headers. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
idrequired | string | – | – |
Body
JSON with content-type: application/json. Optional: you can leave the body out.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
type | string | – | session.started, session.expiring, session.stopped, session.deleted, agent_run.started, agent_run.waiting, agent_run.resumed, agent_run.finished, captcha.waiting, captcha.solved, captcha.failed, crawl.finished, task_run.started, task_run.finished, task.schedule_paused, usage.limit_reached, api_key.created, api_key.revoked, credential.code_needed, credential.changed, webhook.changed, webhook.disabled, extension.uploaded, extension.deleted | An event type (not "*"), or webhook.test (the default). |
curl -X POST "https://api.boxline.dev/v1/webhooks/$WEBHOOK_ID/test" \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "content-type: application/json" \ -d '{"type": "agent_run.waiting"}'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst delivery = await bx.webhooks.test("WEBHOOK_ID", { type: "agent_run.waiting" }); // waits up to 12 s for your answerconsole.log(delivery.status, delivery.responseStatus, delivery.errorCode);from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLdelivery = bx.webhooks.test("WEBHOOK_ID", type="agent_run.waiting") # waits up to 12 s for your answerprint(delivery["status"], delivery["responseStatus"], delivery["errorCode"])Responses
200 OK
The delivery (status stays pending if the answer took longer than 12 seconds).
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
id | string | – | – | |
endpointId | string | – | – | |
eventId | string | – | – | The event's id (the same on every endpoint and every attempt). |
eventType | string | – | – | |
test | boolean | – | – | |
status | string | – | pending, delivered, failed | pending: waiting for its next attempt; failed: no more attempts. |
attempts | integer | – | – | |
nextAttemptAt | string | null | – | – | Format: date-time. |
lastAttemptAt | string | null | – | – | Format: date-time. |
deliveredAt | string | null | – | – | Format: date-time. |
responseStatus | integer | null | – | – | The last answer's HTTP status (null when there was none). |
responseBody | string | null | – | – | The first 1 KB of the last answer (kept 7 days). |
durationMs | integer | null | – | – | |
error | string | null | – | – | Why the last attempt failed. |
errorCode | string | null | – | bad_status, gone, timeout, connection_failed, tls_failed, address_not_allowed, gateway_unavailable, endpoint_disabled, project_suspended, payload_expired, queue_full, signing_failed, null | Why a delivery (or an attempt) failed; null when delivered. The last five are deliveries that were never sent (queue_full: the project already had 10,000 deliveries waiting). |
history | object[] | – | – | The last 20 attempts. |
history[].at | string | – | – | Format: date-time. |
history[].status | integer | null | – | – | |
history[].durationMs | integer | – | – | |
history[].error | string | null | – | – | |
history[].errorCode | string | null | – | bad_status, gone, timeout, connection_failed, tls_failed, address_not_allowed, gateway_unavailable, endpoint_disabled, project_suspended, payload_expired, queue_full, signing_failed, null | Why a delivery (or an attempt) failed; null when delivered. The last five are deliveries that were never sent (queue_full: the project already had 10,000 deliveries waiting). |
payload | any | – | – | The body that was sent (the event); null after 7 days. |
createdAt | string | – | – | Format: date-time. |
{ "id": "dlv_4fJx0aQm2Lk9Pz7N", "endpointId": "…", "eventId": "…", "eventType": "…", "test": false, "status": "pending", "attempts": 0, "nextAttemptAt": "2026-09-29T10:00:00.000Z", "lastAttemptAt": "2026-09-29T10:00:00.000Z", "deliveredAt": "2026-09-29T10:00:00.000Z", "responseStatus": 0, "responseBody": "…", "durationMs": 0, "error": "…", "errorCode": "bad_status", "history": [ { "at": "2026-09-29T10:00:00.000Z", "status": 0, "durationMs": 0, "error": "…", "errorCode": "bad_status" } ], "payload": null, "createdAt": "2026-09-29T10:00:00.000Z"}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 404 Not Found | not_found, invite_not_found, provider_unavailable | No such thing in this project (or organization), or no such route. |
| 429 Too Many Requests | rate_limited, concurrency_limit | Too many requests, or the organization's concurrent sessions (its plan's) or the project's concurrencyCap are in use. |
| 503 Service Unavailable | no_capacity, proxy_unavailable, provider_unavailable, search_unavailable, webhooks_unavailable, mail_unavailable, browser_unreachable | No machine free in time, proxies not set up, the model provider is not configured or has no key, or web search is not set up or its provider is not answering, or webhook delivery is not set up, or an email cannot be sent, or the session's browser did not answer in time. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.