Test Webhook Connection | Speechify API

Probe a customer-supplied webhook tool config without persisting anything. The server fires the exact request shape the worker sends on a real invocation — same JSON body, same HMAC-SHA256 signature — with an empty argument set, and reports the endpoint’s status code, latency, and a truncated response body, or a transport-level failure reason. The probe carries an X-Speechify-Webhook-Test: true header so a careful endpoint can recognise the test and skip its real side effect. Pass tool_id from the edit-form flow so the server signs the probe with the tool’s stored HMAC secret.

Probe a customer-supplied webhook tool config without persisting anything. The server fires the exact request shape the worker sends on a real invocation — same JSON body, same HMAC-SHA256 signature — with an empty argument set, and reports the endpoint's status code, latency, and a truncated response body, or a transport-level failure reason. The probe carries an `X-Speechify-Webhook-Test: true` header so a careful endpoint can recognise the test and skip its real side effect. Pass `tool_id` from the edit-form flow so the server signs the probe with the tool's stored HMAC secret.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

configobjectRequired

Config shape for kind=webhook.

tool_idstringOptional

Optional tool_<crockford> id of the existing tool to sign the probe with. Raw UUIDs and other-resource prefixes are rejected.

Response

Probe result. The 200 envelope is used for both success and structured failure — inspect error to disambiguate. A non-2xx response from the endpoint is NOT an error: it populates status_code / response_body with ok=false. Transport and validation failures never bubble up as non-2xx so the console can render them inline next to the form.

Probe result. The 200 envelope is used for both success and structured failure — inspect `error` to disambiguate. A non-2xx response from the endpoint is NOT an `error`: it populates `status_code` / `response_body` with `ok=false`. Transport and validation failures never bubble up as non-2xx so the console can render them inline next to the form.

okboolean

signedboolean

Whether the probe request carried an HMAC signature header.

status_codeinteger

HTTP status the endpoint returned. Absent on a transport failure.

latency_mslong

Wall-clock round-trip time in milliseconds.

response_bodystring

Truncated prefix (max ~2 KiB) of the endpoint’s response body.

errorstring

Human-readable transport-level failure reason. Absent when any response was received.

Errors

400

Bad Request Error

401

Unauthorized Error

$	curl -X POST https://api.speechify.ai/v1/agents/tools/test-webhook-connection \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"config": {
>	"url": "string"
>	}
>	}'

1	{
2	"ok": true,
3	"signed": true,
4	"status_code": 1,
5	"latency_ms": 1,
6	"response_body": "string",
7	"error": "string"
8	}