How do I create a webhook?

How do I create a webhook?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How do I create a webhook?

When integrating telephony platforms like Tropo or Nexmo into your application, you are often asked to provide an endpoint for webhooks. The confusion usually stems from treating these endpoints as static pages rather than dynamic API routes. You don't need a generic PHP file sitting in your public folder; you need a route that accepts POST requests and returns a JSON response immediately.

The code snippet you found highlights the core mechanics of handling these requests. It correctly starts by setting the Content-Type: application/json header and reading the raw input using file_get_contents('php://input'). This is standard for any framework or raw PHP script receiving a JSON payload. The logic then decodes this string into an associative array to inspect the incoming event data, specifically looking at $request["result"]["action"] to determine the next step in the conversation flow.

However, there is a critical pitfall in that specific example: accessing $_GET['param1value'] or defining variables like $outputtext without populating them first. If the incoming webhook contains parameters you expect, they are nested within the JSON payload, not global variables. You must extract them from the decoded request object before constructing your response. For instance, if the Tropo server sends result.parameters.phone_number, you should grab that value directly to decide what speech output to generate next.

Once you have parsed the incoming data and constructed your $output array—containing keys like contextOut, speech, displayText, and source—you must echo the JSON-encoded string immediately. Do not wrap this logic in a longer script that waits for user interaction; telephony platforms expect an immediate response to continue the session.

Storing Data from Webhooks

The second part of your question involves persisting data received from these events. You asked where to include the storage logic: is it in your API or the webhook file? The answer lies in architectural boundaries. Your webhook endpoint should be responsible solely for processing the request and responding quickly. It should not contain complex business logic or heavy database operations if they introduce latency.

For a robust architecture, treat your webhook receiver as an event listener. When you receive a call event (like Speak or Disconnect) containing user data, extract that information from $request. If you are using a modern framework like Laravel, this is often handled by defining a specific route that listens for these POSTs. Inside that controller, you can push the extracted data to a queue or execute a direct database insert depending on your performance needs.

If you choose to process the data synchronously within the webhook handler, ensure the database write happens before you echo the JSON response. If the database operation fails, you might need to return an error status code, though most telephony platforms are lenient and will simply re-trigger the event or move on. Using a library like LaravelQueue is often preferred here; it allows your webhook endpoint to acknowledge receipt instantly while deferring the heavy lifting of storing records in your DB to a background worker.

Common Pitfalls

A frequent mistake developers make is trying to handle session state across multiple requests without proper context management. Each webhook call is stateless regarding your server's memory unless you explicitly store it. Ensure your $output["contextOut"] array is populated with the correct keys and parameters that Tropo or Nexmo expects for the next node in the conversation tree.

Finally, verify that your server returns a valid JSON response every time. If your script encounters an error, ensure you catch exceptions and return a default failure message rather than letting PHP output a raw stack trace, which will break the telephony session. By treating the webhook as a stateless API endpoint that decodes input, processes logic, and immediately responds with JSON, you create a reliable bridge between your application and the telephony platform.

Our network