Webhooks liefern aYOUne-Events in Echtzeit an deinen HTTP-Endpoint — ohne Polling, ohne Cron. Du registrierst eine URL und einen Event-Filter; die Plattform sendet alle Events, die zum Filter passen, als signiertes JSON-POST.
Wann Webhooks sinnvoll sind
- Neuer Lead/Consumer im CRM → ERP-System anlegen
- Coupon eingelöst → Shop-Bestand reduzieren
- Pipeline grün → Slack-Notification
- Custom-Function-Ergebnis → Drittsystem füttern
Wenn du Pull statt Push brauchst, sind die REST-API Basics der richtige Weg.
Webhook anlegen
curl -X POST https://automation-api.ayoune.app/webhooks \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Lead -> HubSpot",
"url": "https://hooks.example.com/incoming/abc123",
"events": ["consumers.created", "consumers.updated"],
"secret": "wh_secret_min32chars_xxxxxxxxxxxxxxxxx",
"active": true
}'
| Feld | Pflicht | Beschreibung |
|---|---|---|
name |
ja | Anzeige-Name |
url |
ja | Empfänger (HTTPS empfohlen) |
events |
ja | Array aus <plural>.<verb> |
secret |
nein | min. 32 Zeichen für HMAC-Signatur |
active |
nein | default true |
headers |
nein | Zusätzliche Request-Header |
Event-Format
Jeder Webhook-Aufruf ist ein POST mit folgendem Body:
{
"event": "consumers.created",
"timestamp": "2026-04-25T10:00:00.000Z",
"customer": "64a1b2c3d4e5f60012345678",
"data": { "_id": "...", "email": "max@example.com", "first_name": "Max" }
}
Signatur prüfen
Die Plattform setzt den Header X-aYOUne-Signature auf sha256=<HMAC-SHA256(secret, body)>. Verifiziere ihn in deinem Endpoint:
import crypto from "crypto";
function verify(req) {
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.WH_SECRET!)
.update(req.rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(req.headers["x-ayoune-signature"]),
);
}
Retries
Antwortet dein Endpoint nicht mit 2xx, wiederholt die Plattform mit exponential backoff (max. 5 Versuche, 1 min → 16 min). Nach 5 Fehlversuchen landet das Event in der webhookretries-Collection und kann via Admin-UI oder ay webhooks retry <id> reanimiert werden.
Lokale Tests
Für lokale Entwicklung empfiehlt sich ngrok oder Cloudflare-Tunnels:
ngrok http 3000
# Public URL als webhook.url eintragen
Siehe auch: Automation-Module.