WhatsApp REST API, API Keys and Webhooks for Developers

Wazy’s WhatsApp API for developers sits on top of Meta’s Cloud API. Send OTPs, receipts and alerts from your backend with one API key, receive signed webhooks, and try every call in the live playground before you write code.

Send a template in one request

Authenticate with an API key and send templates, text, media, interactive and location messages with plain JSON. Each send returns the WhatsApp message ID, so you can match the delivery webhooks that follow.

  • Scoped API keys per WhatsApp number
  • Templates, text, media, buttons, lists and location
  • Clear errors with Meta codes passed through
POST https://api.wazy.africa/api/v1/messages/template
Authorization: Bearer wa_YOUR_KEY
Content-Type: application/json

{
  "to": "254712345678",
  "template": "order_shipped",
  "language": "en",
  "variables": ["Wanjiku", "#2041"]
}

200 OK
{ "wamid": "wamid.HBgMMjU0NzEy..." }

Events delivered to your endpoint

Get incoming messages and delivery updates at your own URL, plus contact, conversation, template and campaign events. Every payload is signed so you can prove it came from Wazy.

  • message.received, message.delivered, message.read and message.failed
  • HMAC-SHA256 signature on every delivery
  • Automatic retries if your endpoint is down

OTP and authentication templates

Send one-time passcodes with Meta’s authentication templates, including a copy-code button, for logins and payment confirmations.

  • Authentication template category
  • Copy-code button
  • Delivery status by webhook

How to Generate Your WhatsApp API Key & Access Token

With Wazy, the API key is your access token. You don’t create a Meta system user or copy a Graph API token: Wazy holds the Meta access token for your number, encrypted at rest, and your code only ever sends the Wazy key.

  1. Connect your number. Finish Meta’s Embedded Signup in the portal. Keys can only be issued for a connected WhatsApp number.
  2. Open Settings, then API keys. Click Create key, give it a name such as "Production OTP" and pick its scopes. The default is messages:send; add templates:read, contacts:write or webhooks:manage only if that service needs them.
  3. Lock it down. Optionally restrict the key to your server’s IP addresses or, for browser calls, to your website’s domains, and set it to expire after a number of days.
  4. Copy it once. The key looks like wa_ followed by two random strings and is shown a single time. Wazy stores only a SHA-256 hash, so a lost key can’t be recovered. Revoke it and make a new one.
  5. Send it as a Bearer token. Put it in the header as Authorization: Bearer wa_…, in an environment variable, never in front-end code or a Git repository.

API keys come with the Growth plan (5 keys) and the Pro plan (50 keys). Each key handles up to 100 requests a minute; past that the API answers 429 with a Retry-After header.

WhatsApp API integration examples: send an OTP, receive a webhook

Login codes use an authentication template with a copy-code button. Get one approved in the portal first, then pass the code twice: once for the message body and once for the button.

cURL

curl -X POST https://api.wazy.africa/api/v1/messages/template \
  -H "Authorization: Bearer $WAZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "2348031234567",
    "template": "login_code",
    "language": "en",
    "components": [
      {"type": "body", "parameters": [{"type": "text", "text": "482913"}]},
      {"type": "button", "sub_type": "url", "index": "0",
       "parameters": [{"type": "text", "text": "482913"}]}
    ]
  }'

Node.js

// Node.js 18+ (built-in fetch)
async function sendOtp(phone, code) {
  const res = await fetch('https://api.wazy.africa/api/v1/messages/template', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.WAZY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: phone,                 // e.g. '254712345678'
      template: 'login_code',
      language: 'en',
      components: [
        { type: 'body', parameters: [{ type: 'text', text: code }] },
        { type: 'button', sub_type: 'url', index: '0', parameters: [{ type: 'text', text: code }] },
      ],
    }),
  });
  if (!res.ok) throw new Error(`Wazy ${res.status}: ${await res.text()}`);
  return (await res.json()).wamid;
}

PHP

<?php
$code = '482913';
$payload = [
    'to' => '27821234567',
    'template' => 'login_code',
    'language' => 'en',
    'components' => [
        ['type' => 'body', 'parameters' => [['type' => 'text', 'text' => $code]]],
        ['type' => 'button', 'sub_type' => 'url', 'index' => '0',
         'parameters' => [['type' => 'text', 'text' => $code]]],
    ],
];
$ch = curl_init('https://api.wazy.africa/api/v1/messages/template');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WAZY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);
echo $result['wamid'] ?? 'Send failed';

Python

import os
import requests

def send_otp(phone: str, code: str) -> str:
    r = requests.post(
        "https://api.wazy.africa/api/v1/messages/template",
        headers={"Authorization": f"Bearer {os.environ['WAZY_API_KEY']}"},
        json={
            "to": phone,  # e.g. "233241234567"
            "template": "login_code",
            "language": "en",
            "components": [
                {"type": "body", "parameters": [{"type": "text", "text": code}]},
                {"type": "button", "sub_type": "url", "index": "0",
                 "parameters": [{"type": "text", "text": code}]},
            ],
        },
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["wamid"]

Every successful call returns a wamid. Store it next to the login attempt, then watch for message.delivered or message.failed on your webhook. Meta bills each authentication message: $0.0040 in Kenya and Ghana, $0.0067 in Nigeria and $0.0095 in South Africa.

The webhook payload

Add your endpoint under Webhooks in the portal, or with POST /api/v1/webhooks, and choose the events you want. Wazy shows the signing secret once when you create it. Each delivery is a JSON POST like this one:

{
  "id": "6f1c0e9a2b7d4c13e8a05f21",
  "type": "message.received",
  "createdAt": "2026-10-22T09:41:07.512Z",
  "data": {
    "wamid": "wamid.HBgMMjU0NzEy...",
    "from": "254712345678",
    "type": "text",
    "timestamp": "1792662067",
    "contact": { "waId": "254712345678", "name": "Wanjiku" },
    "message": { "type": "text", "text": { "body": "Is my order ready?" } }
  }
}

The X-Webhook-Signature header holds sha256= plus an HMAC-SHA256 of the raw body, keyed with your signing secret. Check it before you trust the payload, and answer with any 2xx status within a few seconds.

Verify and handle it in Node.js

// Express: verify the signature on the raw body, then handle the event
import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.post('/wazy/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WAZY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const given = req.get('X-Webhook-Signature') || '';
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  if (event.type === 'message.failed') console.warn(event.data.wamid, event.data.errors);
  res.sendStatus(200); // reply fast; do slow work in a queue
});
app.listen(3000);

Python (Flask)

# Flask
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WAZY_WEBHOOK_SECRET"].encode()

@app.post("/wazy/webhook")
def wazy_webhook():
    expected = "sha256=" + hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Webhook-Signature", "")):
        abort(401)
    event = request.get_json()
    if event["type"] == "message.delivered":
        print("delivered", event["data"]["wamid"])
    return "", 200

PHP

<?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('WAZY_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);   // $event['type'], $event['data']
http_response_code(200);

If your endpoint fails or times out, Wazy tries again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours and 6 hours. Prefer polling? GET /api/v1/events returns the same events for 14 days, with no public URL needed.

How secure is WhatsApp API communication for business transactions?

Each hop is encrypted. WhatsApp encrypts messages between the customer’s phone and Meta’s Cloud API, and Meta, Wazy and your server exchange them over TLS. Wazy stores Meta access tokens encrypted with AES-256-GCM, keeps only hashes of API keys, signs webhooks, and protects portal logins with authenticator-app 2FA and role-based access.

Everything included

REST API

Send any message type with JSON.

Webhooks

Incoming messages and status events.

API keys

Create and revoke keys per workspace.

Playground

Try calls live before you write code.

OTP templates

Authentication messages with copy-code.

Docs

Guides and reference for every endpoint.

Common questions

Ask us on WhatsApp
Is there a WhatsApp API sandbox for testing?

No separate sandbox. The API playground in the portal makes real calls from your own connected number, so test with your own phone or a colleague’s while you build. Each call shows the live response, and the playground writes the same request for you in cURL, Node.js, PHP and Python.

Can I send WhatsApp OTP codes with a copy-code button?

Yes. Create an authentication template with a copy-code button and get it approved, then POST to /api/v1/messages/template with the code in the body and button parameters. Meta bills each one as an authentication message: $0.0040 in Kenya and Ghana, $0.0067 in Nigeria and $0.0095 in South Africa.

Which Wazy plans include the WhatsApp REST API?

Two: Growth and Pro. Growth includes 5 API keys and Pro includes 50, while Starter has no API access. You can upgrade from Starter at any time, and unused days on your paid plan carry over to the new one. Compare limits on the pricing page.

Are Wazy webhooks signed?

Yes. Every delivery carries an X-Webhook-Signature header: sha256= followed by an HMAC-SHA256 of the raw body, keyed with your endpoint’s signing secret. Compare it in constant time before trusting the payload. The secret is shown once when you create the webhook, and you can rotate it later.

What happens if my webhook endpoint is down?

Six retries follow the first attempt: after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours and 6 hours. Any non-2xx answer or a timeout counts as a failure, and redirects are not followed. Missed events also stay available from GET /api/v1/events for 14 days.

Do I need a Meta access token to use the Wazy API?

No. Wazy holds the Meta access token for your connected number and stores it encrypted with AES-256-GCM. Your code only sends the Wazy API key as a Bearer token, so you never manage Meta system users, app secrets or Graph API versions. See the security page for details.

Start the conversation.

Set up your WhatsApp Business API today and send your first campaign this week.

Customers shopping at a market stall in Accra