Webhook

Endpoint webhook ialah URL pada pelayan anda yang dipanggil oleh WbizTool apabila sesuatu berlaku pada mesej: ia dihantar, gagal, dibatalkan atau tamat tempoh. Anda mendapat berita itu serta-merta tanpa meninjau berulang kali, dan setiap permintaan ditandatangani supaya anda boleh menyemak bahawa ia datang daripada WbizTool.

Endpoint dimiliki oleh ruang kerja dan menerima peristiwa untuk semua mesejnya, tidak kira apa yang menghantarnya: API, papan pemuka, kempen, peringatan atau integrasi. Itulah sebabnya kunci yang dihadkan kepada sebahagian nombor tidak boleh mengurusnya: setiap panggilan menjawab 403 number_not_allowed.

Peristiwa#

Peristiwa untuk nombor (disambungkan, log keluar) dan untuk mesej masuk akan datang kemudian. Tanda sampai dan dibaca tidak menghantar peristiwa; dapatkan mesej itu untuk melihatnya.

Tambah endpoint#

Satu ruang kerja boleh mempunyai sehingga 5 endpoint. Responsnya ialah 201 dengan endpoint dan secret tandatangannya, yang dipaparkan kali ini sahaja. Simpannya di tempat yang boleh dibaca oleh penerima anda, seperti pemboleh ubah persekitaran. Respons kemudian hanya menunjukkan secret_last4; jika anda kehilangan rahsia itu, gantikannya.

curl -X POST https://wbiztool.com/api/v2/webhooks \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/wbiztool/events",
    "events": ["message.sent", "message.failed"],
    "description": "Order system"
  }'

import os
import requests

response = requests.post(
    "https://wbiztool.com/api/v2/webhooks",
    headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
    json={
        "url": "https://example.com/wbiztool/events",
        "events": ["message.sent", "message.failed"],
        "description": "Order system",
    },
    timeout=30,
)
endpoint = response.json()
print("Store this secret now:", endpoint["secret"])

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/webhooks", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com/wbiztool/events",
    events: ["message.sent", "message.failed"],
    description: "Order system",
  }),
});
const endpoint = await response.json();
console.log("Store this secret now:", endpoint.secret);

<?php
$ch = curl_init('https://wbiztool.com/api/v2/webhooks');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'url'         => 'https://example.com/wbiztool/events',
        'events'      => ['message.sent', 'message.failed'],
        'description' => 'Order system',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$endpoint = json_decode(curl_exec($ch), true);
curl_close($ch);
echo 'Store this secret now: ' . $endpoint['secret'];

Respons (201):

{
  "id": 41,
  "url": "https://example.com/wbiztool/events",
  "description": "Order system",
  "events": ["message.sent", "message.failed"],
  "secret_last4": "9c1e",
  "active": true,
  "disabled_reason": null,
  "created_at": "2026-10-18T11:20:05.733Z",
  "last_delivery": null,
  "secret": "3f0b…9c1e"
}

secret yang sebenar ialah 64 aksara heksadesimal. Cubaan semula permintaan ini dengan Idempotency-Key yang sama tidak menambah endpoint kedua, dan responsnya tidak menyertakan rahsia.

Ralat semasa menambah endpoint#

Senaraikan endpoint#

Endpoint ruang kerja yang menerima peristiwa, yang tertua dahulu, dalam satu senarai data.

curl https://wbiztool.com/api/v2/webhooks \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Senarai ini tidak menyertakan endpoint yang telah berhenti. Pemilik juga boleh melihat endpoint, dan membuangnya, di Tetapan → Kunci API di bawah Endpoint webhook.

Dapatkan endpoint#

Satu endpoint. last_delivery menunjukkan keputusan penghantaran terakhirnya. Endpoint yang tidak wujud atau telah dibuang menjawab 404 webhook_not_found; endpoint yang telah berhenti dipaparkan dengan active: false.

Buang endpoint#

Tiada apa-apa lagi dihantar kepadanya, termasuk cubaan semula yang masih menunggu. Responsnya ialah {"id": 41, "deleted": true}.

Ganti rahsia tandatangan#

Mencipta rahsia baharu untuk endpoint. Responsnya ialah 200 dengan endpoint dan secret baharunya, yang dipaparkan kali ini sahaja. Rahsia lama berhenti serta-merta: peristiwa yang dihantar selepas ini ditandatangani dengan rahsia baharu, termasuk cubaan semula peristiwa terdahulu. Kemas kini penerima anda dengan segera.

curl -X POST https://wbiztool.com/api/v2/webhooks/41/rotate-secret \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Hantar peristiwa ujian#

Memasukkan peristiwa ping ke dalam baris gilir untuk endpoint ini, ditandatangani seperti setiap peristiwa, supaya anda boleh menguji penerima anda. Responsnya ialah 202:

{ "event_id": "evt_8a2f4c1d9b7e6a5f4c3b2a19", "type": "ping", "queued": true }

Endpoint anda menerima:

{
  "id": "evt_8a2f4c1d9b7e6a5f4c3b2a19",
  "type": "ping",
  "created_at": "2026-10-18T11:21:40.002Z",
  "data": { "webhook_id": 41 }
}

Payload peristiwa#

Setiap peristiwa ialah POST dengan badan JSON:

{
  "id": "evt_c41d7e2a9f3b8c6d5e4f3a21",
  "type": "message.sent",
  "created_at": "2026-10-18T10:15:09.912Z",
  "data": {
    "message": {
      "id": 9817263,
      "status": "sent",
      "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
      "to": { "phone": "+919876543210", "contact_id": 991 },
      "text": "Hi Asha, your order #1042 is ready.",
      "media": null,
      "send_at": null,
      "expires_at": null,
      "created_at": "2026-10-18T10:15:02.311Z",
      "sent_at": "2026-10-18T10:15:09.870Z",
      "error": null
    }
  }
}

Pengepala:

Sahkan tandatangan#

Semak setiap permintaan sebelum anda mempercayainya: kira tandatangan daripada badan mentah (sebelum rangka kerja anda menghuraikan JSON), bandingkannya dengan pengepala dalam masa malar, dan tolak cap masa yang berbeza lebih daripada 5 minit, supaya permintaan lama tidak boleh dimainkan semula. Ia skema yang sama seperti tandatangan webhook API v1, dengan rahsia endpoint itu sendiri.

Kemudian gunakan WbizTool-Event-Id untuk membuang ulangan: peristiwa yang sama boleh tiba lebih daripada sekali, contohnya apabila respons anda hilang dan kami mencuba lagi.

import hashlib, hmac, json, os, time

SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"]

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers.get("WbizTool-Timestamp", ""), headers.get("WbizTool-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, sig)

# Flask
from flask import Flask, request

app = Flask(__name__)
seen = set()  # use your database in production

@app.post("/wbiztool/events")
def events():
    body = request.get_data()  # the raw bytes
    if not verify(SECRET, body, request.headers):
        return "", 401
    event_id = request.headers["WbizTool-Event-Id"]
    if event_id in seen:
        return "", 200  # a repeat: already handled
    seen.add(event_id)
    event = json.loads(body)
    if event["type"] == "message.failed":
        message = event["data"]["message"]
        print("Failed:", message["id"], message["error"]["message"])
    return "", 200

const crypto = require("crypto");
const express = require("express");

const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

function verify(secret, rawBody, headers) {
  const ts = String(headers["wbiztool-timestamp"] || ""), sig = String(headers["wbiztool-signature"] || "");
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return sig.length === mac.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

const app = express();
const seen = new Set(); // use your database in production

// express.raw keeps the body as a Buffer: the signature covers the exact bytes.
app.post("/wbiztool/events", express.raw({ type: "*/*" }), (req, res) => {
  if (!verify(SECRET, req.body, req.headers)) return res.sendStatus(401);
  const eventId = req.headers["wbiztool-event-id"];
  if (seen.has(eventId)) return res.sendStatus(200); // a repeat: already handled
  seen.add(eventId);

  const event = JSON.parse(req.body);
  if (event.type === "message.failed") {
    const message = event.data.message;
    console.log("Failed:", message.id, message.error.message);
  }
  res.sendStatus(200);
});

app.listen(3000);

Jawab 2xx dengan cepat, kemudian lakukan kerja yang perlahan selepas itu (contohnya dalam baris gilir).

Cubaan semula#

• Jawab dengan sebarang 2xx dalam masa 10 saat. Selain itu dikira sebagai kegagalan: kod status lain (termasuk 4xx), tiada jawapan dalam masa 10 saat, atau tiada sambungan dalam masa 3 saat. Ubah hala diikuti, paling banyak 3 kali, dan setiap satu mesti membawa ke alamat awam.
• Penghantaran yang gagal dicuba semula selepas 1, 5 dan 15 minit, kemudian 1, 2, 4, 8 dan 8 jam: 9 cubaan dalam kira-kira 23 jam. Selepas cubaan terakhir, peristiwa itu digugurkan.
• Cubaan semula mempunyai badan dan WbizTool-Event-Id yang sama, dengan WbizTool-Timestamp dan tandatangan yang baharu.
• Susunan tidak dijamin. message.sent yang dicuba semula boleh tiba selepas peristiwa yang lebih baharu. Gunakan status mesej, atau dapatkan mesej itu, apabila susunan penting.

last_delivery pada endpoint menunjukkan keputusan penghantaran terakhir: state (pending, delivered atau failed), status_code yang dijawab oleh pelayan anda, dan bila peristiwa itu dicipta.

Bila endpoint berhenti#

Endpoint berhenti menerima peristiwa apabila salah satu perkara ini berlaku. Ia kekal dalam GET /webhooks dengan active: false dan disabled_reason, supaya anda boleh melihat sebabnya; ia masih boleh dibaca dan dibuang, tetapi tidak boleh diuji atau diberi rahsia baharu (404).

• Ia telah gagal selama 24 jam. Jika tiada apa-apa berjaya dihantar kepadanya selama 24 jam sementara penghantarannya terus gagal, ia dimatikan dan cubaan semula yang menunggu digugurkan. Tetapan → Kunci API kemudian memaparkannya sebagai Tidak aktif. Betulkan pelayan anda, kemudian tambah endpoint semula.
• Kunci yang menciptanya ditarik balik atau tamat tempoh. Menarik balik kunci menghentikan semua yang disediakannya. Tambah endpoint semula dengan kunci lain.
• Ia dibuang, dengan Buang endpoint atau di Tetapan → Kunci API.

Endpoint yang telah berhenti tidak dikira dalam had 5.

Objek endpoint webhook#

Berkaitan#

• Mesej: objek Message dalam data.message
• Tandatangan webhook untuk API v1
• Ralat