Developers / Tools
Create a webhook tool
https://api.echonova.ai/v1/tools/webhookCreates a tool that calls one public https URL with the parameters you describe. Secret header values and auth connections are referenced by id; plain values that look like credentials are refused. The request takes the call under webhook.target.url; the response shows it as webhook.url. Send an Idempotency-Key to retry safely. At most 20 calls a minute per key. Secrets are referenced by id from GET /v1/secrets; their values can only be entered in the portal vault. Free. Needs the tools:write scope on the key.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Optional. Repeat the same key within 24 hours to retry safely: the first result comes back and nothing is made twice. A new request needs a new key.
Request body
application/json
Tool name, unique in the workspace.
What the tool does.
The call the tool makes.
Response
200 application/json Every response uses this envelope.
The result.
The tool id.
Tool name, unique in the workspace.
webhook, openapi or integration.
What the tool does, or null.
When the tool was created.
When the tool last changed.
Set for webhook tools. Constant values are never returned.
The URL the tool calls.
HTTP method of the call.
How long the call may take, in milliseconds, or null for the default.
Auth connection id used for the call, or null.
The values the call sends.
Where the parameter goes in the request.
Parameter key, or the path placeholder name.
The type of value the parameter takes.
Whether the call needs this parameter.
Tells the model what to put here, or null.
llm, constant or secret. Constant values are never returned.
The vault secret id when valueType is secret, otherwise null.
Set for OpenAPI tools.
Title of the imported OpenAPI document.
How many operations the tool imported.
Whether the import is ready for agents.
The server the tool calls, or null.
Operation names selected for import, empty for all.
Auth connection id sent on every call, or null.
Why the import failed, or null.
Set for integration tools.
The integration provider.
The integration tool key.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. A parameter or fieldValues entry with valueType constant has a name that looks like a credential, such as Authorization, token, api key or cookie. The message names the field and never its value.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. A constant value starts with Bearer, Basic, Token or Digest, or has the shape of a JWT. The message names the field and never its value.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. The webhook url or baseUrlOverride has a query key that looks like a credential. The message names the key and never its value.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. A credential-like key is hidden in the query or fragment of the webhook url or baseUrlOverride.
Fix. Save the value in the vault in the portal, then send it as a secret header with its secretId, or use an auth connection.
When. The webhook url is not https, or points at a loopback, private or link-local address, or is not a URL.
Fix. Send a public https URL.
When. The webhook url carries a user name or password.
Fix. Send the URL without them, and use a secret header or an auth connection.
When. A secretId, connectionId or authConnectionId is not a 24-character hexadecimal id; the message names the field.
Fix. Use an id from GET /v1/secrets or GET /v1/auth-connections.
When. A secretId is unknown or belongs to another workspace.
Fix. Use an id from GET /v1/secrets.
When. A connectionId or authConnectionId is unknown, belongs to another workspace, or is a connection a channel manages.
Fix. Use an id from GET /v1/auth-connections.
When. A parameter has valueType secret and no secretId; the message names it.
Fix. Send the secretId from GET /v1/secrets.
When. A parameter with valueType secret is not in the header location; the message names it.
Fix. Send the secret as a header parameter.
When. The webhook url has a {placeholder} with no path parameter of that name.
Fix. Add a path parameter for each placeholder.
When. A path parameter has no {name} in the webhook url.
Fix. Put {name} in the url, or remove the parameter.
When. A GET or DELETE webhook has a body parameter; the message names the method.
Fix. Use a query parameter, or POST, PUT or PATCH.
When. A parameter name is empty.
Fix. Give every parameter a name.
When. Two parameters share a location and name; the message names them.
Fix. List each parameter once.
When. A parameter has valueType constant and no constantValue.
Fix. Send constantValue.
When. The Idempotency-Key header is longer than 200 characters, or holds a space or a character outside printable ASCII.
Fix. Send 1 to 200 printable ASCII characters, such as a UUID.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key does not have the tools:write scope. agents:write does not give it.
Fix. Edit the key and give it the tools:write scope, or use another key.
When. The member who created the key has left the workspace, or no longer has both the Manage tools and Manage developer API permissions. It is checked on every call.
Fix. Give that member both permissions again, or create a key as a member who has them.
When. Another tool in the workspace has this name; the message names it.
Fix. Pick another name.
When. This key sent the same Idempotency-Key in the last 24 hours with a different body or agent.
Fix. Use a new Idempotency-Key for a new request.
When. The first request with this Idempotency-Key has not finished yet.
Fix. Wait a moment, then retry with the same key to get its result.
When. The JSON body is over 100 KB; the request is rejected before the API key is checked, so it has no Activity row.
Fix. Send a smaller body; long text belongs in several calls.
When. The request has a body whose Content-Type is not application/json.
Fix. Send Content-Type: application/json.
When. The key made more than 20 requests to this endpoint in 60 seconds; a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl -X POST "https://api.echonova.ai/v1/tools/webhook" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Order lookup","webhook":"string"}'{
"data": {
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Order lookup",
"type": "webhook",
"description": "Finds an order by its number.",
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-01T10:00:00.000Z",
"webhook": {
"url": "https://api.example.com/orders/{orderId}",
"method": "GET",
"timeoutMs": 10000,
"connectionId": "6650a1b2c3d4e5f6a7b8c9d0",
"parameters": [
{
"location": "header",
"name": "orderId",
"dataType": "string",
"required": true,
"description": "Finds an order by its number.",
"valueType": "llm",
"secretId": "YOUR_SECRET_ID"
}
]
},
"openapi": {
"apiTitle": "Orders API",
"operationCount": 12,
"status": "ready",
"baseUrl": "https://api.example.com",
"includeOperations": [
"getOrder"
],
"authConnectionId": "YOUR_AUTH_CONNECTION_ID",
"error": null
},
"integration": {
"provider": "slack",
"key": "add_reaction"
}
},
"success": true,
"statusCode": 200,
"errorMessage": null
}