Skip to Content
Wapitick developers

Receive messages by webhook

Register an endpoint, verify every delivery, and answer fast.

  1. Register your endpoint (or use npx wapitick listen while you build).
  2. Verify the signature on the raw body before you parse it.
  3. Answer 200 within 10 seconds and do slow work afterwards; de-duplicate on the event id.

cURL

curl.sh
#!/usr/bin/env bash
# Receive messages by webhook: webhook_endpoints_create, test_inbound_create (runs in test mode)
set -euo pipefail
API="${WAPITICK_API_URL:-https://api.wapitick.com}"
AUTH="Authorization: Bearer $WAPITICK_API_KEY"

# Register your HTTPS endpoint for incoming messages. The secret is shown ONCE: store it.
curl -sf "$API/v1/webhook-endpoints" -H "$AUTH" -H "Content-Type: application/json" -H "Idempotency-Key: wh-$(date +%s)" \
  -d "{\"url\":\"${WEBHOOK_URL:-https://example.com/wapitick/webhooks}\",\"events\":[\"message.received\",\"message.status_updated\"]}" \
  | jq '{id: .endpoint.id, livemode: .endpoint.livemode, secret_starts: (.secret[0:6])}'
# Fire one (test mode)
curl -sf "$API/v1/test/inbound" -H "$AUTH" -H "Content-Type: application/json" -H "Idempotency-Key: wh-in-$(date +%s)" \
  -d '{"from":"+15550100001","text":"Hello webhook"}' | jq '{status}'
# No public URL yet? `npx wapitick listen --forward-to http://localhost:3000/webhooks` streams the same events.

Node

node.mjs
// biome-ignore-all lint/suspicious/noConsole: a docs sample prints its result
// Receive messages by webhook: a tiny server that verifies every delivery (verifyWebhook) and answers 200 fast.
import { createServer } from "node:http";
import { verifyWebhook } from "@wapitick/node";

const secret = process.env.WAPITICK_WEBHOOK_SECRET ?? "whsec_test";
const server = createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    try {
      const event = verifyWebhook(Buffer.concat(chunks), req.headers, secret); // the RAW body
      if (event.type === "message.received") console.log("from", event.data.object.contact_id);
      res.writeHead(200).end(); // answer within 10 s; do slow work after
    } catch {
      res.writeHead(400).end();
    }
  });
});
if (process.env.CI_SAMPLE !== "1") server.listen(Number(process.env.PORT ?? 3000));
else console.log(JSON.stringify({ ok: true }));

Python

python.py
# Receive messages by webhook (Flask): verify every delivery, answer 200 fast.
import json
import os

from wapitick import verify_webhook

SECRET = os.environ.get("WAPITICK_WEBHOOK_SECRET", "whsec_test")


def handle(raw_body: bytes, headers: dict) -> int:
    event = verify_webhook(raw_body, headers, SECRET)  # the RAW body
    if event["type"] == "message.received":
        print("from", event["data"]["object"].get("contact_id"))
    return 200


if os.environ.get("CI_SAMPLE") == "1":
    print(json.dumps({"ok": True}))
else:
    from flask import Flask, request  # pip install flask

    app = Flask(__name__)

    @app.post("/webhooks")
    def webhooks():
        try:
            return "", handle(request.get_data(), dict(request.headers))
        except Exception:
            return "", 400

    app.run(port=int(os.environ.get("PORT", 3000)))

PHP

php.php
<?php
// Receive messages by webhook (plain PHP or a Laravel route): verify every delivery, answer 200 fast.
require __DIR__ . '/vendor/autoload.php';

try {
    $event = Wapitick\Webhook::verify(file_get_contents('php://input'), getallheaders(), getenv('WAPITICK_WEBHOOK_SECRET'));
    if ($event['type'] === 'message.received') {
        error_log('from ' . ($event['data']['object']['contact_id'] ?? '?'));
    }
    http_response_code(200);
} catch (Wapitick\WapitickException $e) {
    http_response_code(400);
}

Operations: webhook_endpoints_create, test_inbound_create. Details: Webhooks.

This page as Markdown