Template Delivery Report (Webhook)

This page explains how Template Delivery Reports work — i.e. how you get notified when WhatsApp approves or rejects a template you submitted, without having to poll our API.

The flow has two parts:

You configure a webhook once — tell us the URL (and optional token) where we should send updates.
We send you a report automatically — every time one of your templates is approved or rejected, we push the result straight to that URL. No polling needed.

Step 1: Configure Your Webhook

Before you can receive any delivery reports, a webhook must be registered for your username.

Field	Type	Required	Description
`username`	string	Yes	Your account username — reports for all templates under this username go to the same webhook.
`url`	string (URL)	Yes	The HTTPS endpoint on your server that will receive the report.
`token`	string	No	Sent as-is in the request headers on every delivery, so you can authenticate the incoming call (e.g. `Authorization: Bearer xxxx`).
`status`	integer	—	`1` = active (webhook is live), `0` = paused. Only active webhooks receive reports.

Only one active webhook per username is used at a time. If more than one is configured, the most recently updated active one wins.

Reach out to enable/update your webhook URL and token, or use the webhook management endpoint if you've been given access to one.

Step 2: How the Report Is Sent

Once your webhook is active, here's what happens behind the scenes — no action needed from you:

When you create a template, it starts in pending status.
Our system checks WhatsApp's approval status periodically.
As soon as a template's status changes to approved or rejected/failed, a report is generated for it.
That report is sent as an HTTP POST request, in JSON, to your registered webhook url.
If your token is set, it's attached to the request so you can verify the call came from us.
Each report is sent only once per template — once delivered (success or failure on our end), it won't be resent.
Every attempt is logged on our side (URL called, payload sent, response received, success/failure) so delivery can be traced if something goes wrong on your end.

Report Payload

This is exactly what lands on your webhook URL:

{
  "template_name": "order_confirmation",
  "username": "salesindia",
  "status": "approved",
  "reason": ""
}

Field	Type	Description
`template_name`	string	The name of the template this report is about.
`username`	string	Your username (useful if one endpoint receives reports for multiple accounts).
`status`	string	Either `"approved"` or `"failed"`.
`reason`	string	Populated only when `status` is `"failed"` — explains why WhatsApp rejected the template. Empty string when approved.

Request Headers

Header	Value
`Content-Type`	`application/json`
Your configured token (if set)	sent as-is, e.g. `Authorization: Bearer <your_token>`

What You Should Return

Your endpoint just needs to respond with an HTTP 2xx status code to acknowledge receipt. Any response body is accepted — we log it for reference, but don't parse it.

{ "received": true }

Example: Receiving the Report (PHP)

<?php
// your-server.com/webhook/template-report.php

$expectedToken = "Bearer your_secret_token"; // matches the token you registered
$authHeader = $_SERVER["HTTP_AUTHORIZATION"] ?? "";

if ($authHeader !== $expectedToken) {
  http_response_code(401);
  echo json_encode(["received" => false, "message" => "Invalid token"]);
  exit;
}

$payload = json_decode(file_get_contents("php://input"), true);

$templateName = $payload["template_name"] ?? "";
$status        = $payload["status"] ?? "";
$reason        = $payload["reason"] ?? "";

if ($status === "approved") {
  // e.g. mark template as live in your own system
} elseif ($status === "failed") {
  // e.g. notify your team with $reason
}

http_response_code(200);
echo json_encode(["received" => true]);

Delivery Status Reference

`status` value	Meaning
`approved`	Template was approved by WhatsApp and is now ready to use.
`failed`	Template was rejected. Check `reason` for details.

Notes

Reports are only sent for templates whose status has actually changed to approved or failed — you won't get a report while a template is still pending.
If your webhook URL is unreachable or returns an error, the failure is logged on our side; make sure your endpoint stays up and responds quickly (avoid long processing before sending back the 2xx).
Keep your token private — anyone with it could send fake reports to your endpoint pretending to be us. Rotate it if you suspect it's been exposed.