Webhook reference

Set the webhook URL on a device. QuackAPI sends an HTTP POST with a JSON body.

message.received

Payload
{
  "event": "message.received",
  "deviceId": 1,
  "from": "923001234567",
  "content": "Hi",
  "timestamp": 1700000000,
  "messageId": "ABC123"
}

message.sent

Payload
{
  "event": "message.sent",
  "messageId": 123,
  "to": "923001234567",
  "deviceId": 1,
  "status": "sent"
}

message.failed and message.unknown

Payload
{
  "event": "message.failed",
  "messageId": 123,
  "to": "923001234567",
  "deviceId": 1,
  "error": "reason"
}

Receiving them

  • Answer with a 2xx quickly and do the real work afterwards.
  • Webhooks are not signed today, so keep the URL secret and unguessable, and check the fields you rely on.
  • Handle duplicates: use messageId to make processing idempotent.
  • Check the webhook log on the device page if nothing arrives.

Example receiver: Node.js

Express
import express from 'express';
const app = express();
app.use(express.json());
const seen = new Set();

app.post('/hooks/whatsapp', (req, res) => {
  res.sendStatus(200);
  const e = req.body;
  const key = e.event + ':' + e.messageId;
  if (seen.has(key)) return;
  seen.add(key);
  if (e.event === 'message.received') console.log('from', e.from, e.content);
  if (e.event === 'message.failed') console.log('failed', e.messageId, e.error);
});

app.listen(3000);

Example receiver: Python

Flask
from flask import Flask, request
app = Flask(__name__)

@app.post('/hooks/whatsapp')
def hook():
    e = request.get_json(force=True)
    if e.get('event') == 'message.received':
        print('from', e['from'], e['content'])
    return '', 200

app.run(port=3000)

Testing locally

  • Run your receiver on a local port.
  • Expose it with a tunnel tool so it has a public https URL.
  • Paste that URL as the device webhook and send yourself a message.
  • Check the webhook log on the device page to see the request and your answer.

FAQ

Are webhooks retried?

Each attempt is recorded in the device webhook log. Make your receiver idempotent with messageId, and answer 2xx quickly.

Can I have one webhook for several devices?

The URL is set per device, so you can point several devices at the same URL and tell them apart with the deviceId field.

Is there a signature to verify?

Not today. Keep the URL unguessable and validate the fields you rely on.

Related

Last reviewed 2026-11-09. QuackAPI is an unofficial linked-device service. Acceptable use