Webhooks

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.