REST API and webhooks
ThunderPhone's REST API and webhooks support two complementary directions of integration. Your software can use the API to create, retrieve, update, deploy, duplicate, transfer, and delete agents. ThunderPhone can send webhook events to your software when call and workflow activity occurs. For a live conversation that needs a business-system action, the integration catalog also provides a custom function path built from a REST endpoint, a cURL command, or API documentation.
These are separate paths. An API request changes or retrieves a ThunderPhone resource. A custom function gives an agent a defined call-time operation. A webhook delivers an event or, on the legacy path, participates in a blocking request-and-response exchange. Keeping those roles separate makes failure handling much clearer.
What the REST API does
Agent configuration uses a draft-and-deploy workflow. Updates are saved to a draft, while production calls continue using the deployed configuration. Tests can exercise the draft, and a deploy request promotes the pending changes. Integrations and MCP servers can be attached through the agent configuration as organization-scoped resources.
A custom REST function is narrower. It should represent one explicit action the agent may need during a call, with defined inputs and a response the agent can interpret. Examples include looking up an approved status or submitting a callback request. The endpoint remains responsible for authentication, input validation, authorization, and an unambiguous success or failure response.
What webhooks do
The recommended webhook model supports multiple endpoints, per-endpoint secrets, and event subscriptions. Deliveries are signed with HMAC-SHA256 over the raw request body. Endpoint notifications retry with exponential backoff when they are not acknowledged, and delivery is at least once, so consumers should deduplicate using the event identifier and tolerate events arriving out of order.
The legacy organization webhook remains available for backward compatibility. It is also the path for blocking incoming-call configuration exchanges and webhook-mode tool dispatch. Endpoint-based webhooks are non-blocking notifications; they do not configure a live call by returning a response.
Typical call flows
Post-call processing
Subscribe an endpoint to completed-call events. After verifying the signature, accept the payload durably, return a successful response, and process slower work asynchronously. A consumer might store the call result, update an internal workflow, or notify a review queue. It should use the event identifier to avoid repeating the same business action after a retry.
Dynamic incoming-call configuration
Use the legacy webhook only when your server must provide configuration as a call arrives. Because this exchange sits on the call path, keep the response fast and define a safe fallback for timeouts or unavailable dependencies.
Call-time business action
Define a custom REST function for a bounded operation and attach it to the relevant agent. The prompt should tell the agent when to call it, which fields are required, and never to claim success until the endpoint confirms the action.
Setup outline
- Create an API credential and keep it on the server side.
- For agent management, build against the relevant REST resources and preserve the draft/deploy boundary.
- For call-time actions, define the smallest useful custom function and test both success and failure responses.
- For event delivery, create webhook endpoints, choose subscriptions, store each endpoint secret, and verify every signature before parsing trusted data.
- Acknowledge durable receipt quickly, deduplicate events, and monitor repeated failures.
- Add the legacy webhook only if the workflow needs blocking call configuration or webhook-mode tool dispatch.