Test Webhook

Send a synthetic event to a webhook to verify connectivity, TLS, and signature handling. The event is generated by PipAI and delivered through the normal pipeline — same headers, same signing, same retry semantics — so a successful test confirms your handler is wired up correctly end to end.

Endpoint

POST /v1/webhooks/{id}/test

Weight: 10 Authentication: Required (signed) — see Authentication.

This endpoint is synchronous: the request blocks until the synthetic delivery completes or times out (10 seconds). Use it sparingly — it has a higher weight than other webhook endpoints because it consumes a delivery slot.

Path parameters

Name	Type	Mandatory	Description
id	string	YES	Webhook identifier, format wh_<6-8 hex>.

Request body

Name	Type	Mandatory	Description
event_type	string	NO	The type field to embed in the synthetic event body. Defaults to webhook.test. Supplying a real event type (e.g. strategy.deployed) is allowed — the data payload will contain dummy values.

Response

{
  "test_event_id": "evt_test_b7f2c1a93d",
  "delivered": true,
  "response_status": 200,
  "response_time_ms": 187,
  "error": null
}

On a delivery failure:

{
  "test_event_id": "evt_test_b7f2c1a93d",
  "delivered": false,
  "response_status": 502,
  "response_time_ms": 412,
  "error": "Endpoint returned non-2xx status"
}

Response fields

Field	Type	Description
test_event_id	string	Identifier of the synthetic event, format evt_test_<10-12 hex>. Test event IDs use the evt_test_ prefix so they can be filtered out of production telemetry.
delivered	boolean	true if the endpoint returned a 2xx status within the 10-second timeout, false otherwise.
response_status	integer|null	The HTTP status returned by the endpoint, or null if the endpoint did not respond (TLS error, connection refused, timeout).
response_time_ms	integer|null	Wall-clock time from request send to response receipt, in milliseconds. null if no response was received.
error	string|null	Human-readable error description on failure, or null on success.

A successful test (delivered: true) resets the webhook's consecutive_failures counter to 0, which is the supported way to recover an active webhook that has accumulated failures without yet hitting the auto-pause threshold.

Errors

• 403 INSUFFICIENT_PERMISSION — the API key lacks the webhooks:write scope.
• 404 NOT_FOUND — no webhook with this id exists on the account.
• 409 INVALID_STATE — the webhook's status is broken. A broken webhook must be reactivated via the dashboard or the (forthcoming) PATCH endpoint before tests can be sent. This guards against accidental traffic against an endpoint that has already failed 50 consecutive deliveries.

Note that a delivery failure (e.g. the endpoint returning a 5xx) is not a request error — the API call itself returns 200 OK with delivered: false in the body. Only metadata-level problems produce non-200 responses.

See Errors for the full list.

Example

curl -X POST "https://api.pipai.example/v1/webhooks/wh_2a4f10/test" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "strategy.deployed"
  }'