Webhooks are a powerful feature of the TNZ API that allow your system to receive real-time updates without having to constantly poll our servers. Instead of asking "has my message been delivered?" every few minutes, TNZ pushes the data to you the moment it happens.
This guide covers how to understand, configure, and use webhooks.
What are Webhooks?
A webhook is an automated message sent from the TNZ system to a specific URL on your server (or a third-party service) when an event occurs.
There are two primary events that trigger a webhook:
-
Delivery Reports: When an outbound message (SMS, Email, Voice, Fax) finishes processing. The webhook confirms if it was delivered successfully or failed, along with cost and timestamp data.
-
Inbound Messages: When a mobile handset replies to your SMS or sends a new message to your dedicated number.
Common Use Cases
Webhooks are essential for building responsive, automated communications systems.
Common implementations include:
-
Database Sync: Automatically updating a "Success" or "Failed" status in your CRM when a message delivery is confirmed.
-
Two-Way Chat: Pushing inbound SMS replies directly into a support ticketing system or Slack channel.
-
Triggered Workflows: using an inbound message to trigger an automation sequence.
Because TNZ webhooks use standard JSON or XML formatted HTTP POST requests, they integrate natively with low-code automation platforms such as Zapier, Make, Microsoft Power Automate, and n8n.
Setting a Default Webhook
You can configure a "catch-all" webhook at the User level. This ensures that any message sent by that specific API user uses these settings.
To configure your default settings:
-
Log in to the TNZ Dashboard.
-
Navigate to Users and select the specific User.
-
Click on the API tab.
Here you can configure the following behaviors:
-
Webhook Callback URL: The default destination URL where TNZ will POST the data.
-
Webhook Callback Format: Choose between JSON (recommended) or XML.
-
Report Methods: For each message type (SMS, Voice, Email, Fax), you can define the rule.
Example: You might set SMS Report Method to "Send me a Webhook" to integrate with an automation, but set Voice Report Method to "Email me if the SMS fails" for users using other TNZ services.
Specifying Webhooks Per Message
For developers building complex applications, you often need to route notifications dynamically. You can override the default dashboard settings on a per-message basis by including specific parameters in your API POST request.
When sending a message, you can pass the following parameters:
| Parameter |
Description |
Potential Values |
| NotificationType |
Specifies the notification method. |
Webhook, Email, None, or leave blank to use defaults. |
| WebhookCallbackURL |
Overrides the default URL. |
https://api.your-app.com/sms-listener |
| WebhookCallbackFormat |
Overrides the default data format. |
JSON, XML, POST, GET |
Refer to your API version's documentation for up-to-date parameters and values.
Example Scenario
You typically send marketing SMS messages that use your default webhook, configured in the TNZ Dashboard.
However, for a specific n8n Automation SMS, you want n8n to send the message, specifying a unique Webhook URL that captures the status report. When sending the message, you could include:
-
NotificationType: "Webhook"
-
WebhookCallbackURL: "https://n8n.domain.com/webhook/abcdefg-1234-9876"
-
WebhookCallbackFormat: "JSON"
Webhook Rules and Specifications
To ensure reliability, the TNZ webhook system adheres to specific technical rules.
Delivery & Retry Logic
-
Method: Webhooks are delivered as an HTTP POST.
-
Retry Policy: If your server returns a 400 or 500 error (or times out), TNZ will retry sending the webhook every 5 minutes.
-
Expiration: Retries continue for a maximum of 24 hours. After this period, the system considers the webhook failed and stops retrying.
The Webhook Payload (JSON)
When your server receives a webhook, it will contain a payload detailing the event.
Check the latest API documentation for samples.
Need help debugging webhooks?
If you are setting up a new integration and are not receiving webhooks, we recommend using a tool like Webhook.site to generate a temporary test URL. Place this URL in your TNZ Dashboard settings to inspect the exact payload TNZ is sending.
Our Postman project also includes ready-made Webhook samples - simply insert your URL and submit!