Webhook Testing and Validation

Webhook Testing and Validation

Configuring a webhook integration can present certain challenges, as different systems may implement HTTP standards with slight variations. To simplify the integration process, SMSPortal provides a suite of testing tools designed to help customers validate their webhook configurations. These tools are described in the sections below.

JSON Validation Tool

When creating an HTTP POST webhook template, it is the customer’s responsibility to ensure the JSON structure is correctly formatted. This includes, but is not limited to:

  • Wrapping string property values in double quotation marks.
  • Optionally casting numeric properties as string values by enclosing them in double quotation marks.
  • Ensuring all property names are correctly enclosed in double quotation marks.
  • Confirming that properties are properly separated by commas, and that no trailing commas exist.
  • Verifying that all object braces ({}) are correctly placed and balanced within the JSON structure.

To assist with this, SMSPortal provides a Preview Data function in the HTTP POST webhook builder. This feature allows customers to preview the JSON request body with example data. If the JSON structure is invalid, the preview will fail to render, clearly indicating an issue that needs correction.

Additionally, developers can easily copy the previewed JSON structure when configuring their webhook endpoint. This helps ensure that endpoints are correctly set up to receive data in the expected format for that webhook type.


Full Pipeline Validation

Once the webhook template and any optional custom headers have been configured, customers must perform a live test to verify end-to-end functionality. This involves sending a test webhook to the target HTTP endpoint (the customer’s server). SMSPortal refers to this as the Test tool.

Webhooks—whether new or edited—cannot be saved until they have successfully passed this test. A failed test indicates that the HTTP pipeline is not functioning correctly, and any attempted webhook delivery would result in failure.

The Test tool provides detailed diagnostic information, including:

  • The IP address of the webhook engine.
  • The resolved request URL (useful for GET requests).
  • The request body sent (useful for POST requests).
  • Any custom headers included in the request.
  • The results of DNS resolution (verifying that the domain resolves to the correct IP address).
  • The outcome of establishing a TCP connection to the destination IP on port 443 (HTTPS).
  • The HTTP response code (a successful test should return a 2xx response).
  • The validity of the SSL/TLS certificate.
  • The response returned by the server. While SMSPortal does not process the response body, it is displayed for the customer’s reference to help understand server behavior. As described in earlier sections, the webhook engine considers a request successful if it receives an HTTP 2xx response, which prevents retries.

Note 1: The Test tool always uses a standard example payload when substituting data into the customer’s configured template. This payload does not represent real data, and customers are not billed for using the test functionality.

Troubleshooting

When troubleshooting always ensure the following:

  • The webhook URL specified is correct, the domain is registered and it resolves to an IP address.
  • The IP addresses from which we will perform HTTP posts are whitelisted on your firewall and that the relevant ports are open.
  • The web server has been configured to host your application.
  • The web server has been configured to allow HTTP posts.
  • You are responding with an appropriate HTTP 2xx code to our inbound requests.

Third-Party Testing Tools

Customers who wish to experiment with webhook integrations but have not yet deployed their own server can use a free webhook inspection service such as https://httpdump.app/. However, be aware that the URLs provided by such tools are typically temporary and may expire after a few days.