Webhooks & Events

Überblick

Webhooks benachrichtigen Ihre Anwendung in Echtzeit wenn sich Daten in aYOUne ändern. Konfiguration über die Admin-UI oder API.

Event-Typen

Jede Entity kann drei Event-Typen auslösen:

Event	Auslöser	Beispiel
{entity}.created	Neues Dokument	consumers.created
{entity}.updated	Dokument geändert	consumers.updated
{entity}.deleted	Dokument gelöscht	consumers.deleted

Payload-Format

{
  "event": "consumers.created",
  "timestamp": "2026-04-12T16:30:00.000Z",
  "customerId": "5a37a07d...",
  "data": {
    "_id": "abc123",
    "first_name": "Anna",
    "email": "anna@example.com",
    // ... alle Felder des Dokuments
  }
}

Konfiguration

• URL — Ihr HTTPS-Endpoint
• Events — Welche Entities und Aktionen (create/update/delete)
• Header — Custom Headers (z.B. API-Key zur Verifizierung)
• Retry — Automatische Wiederholung bei HTTP 5xx (3 Versuche, exponentielles Backoff)

Webhook-Verifizierung Coming Soon

Geplant ist eine HMAC-SHA256-Signatur im X-aYOUne-Signature-Header — kompatibel zum Stripe-Pattern, damit bestehende Helper-Bibliotheken wiederverwendet werden können:

X-aYOUne-Signature: t=1714490400,v1=2c8b...e91f

Der Wert wird als HMAC_SHA256(secret, "{t}.{rawBody}") berechnet, wobei secret das pro Webhook konfigurierte Secret ist und rawBody der unmodifizierte Request-Body. Beispiel-Verifikation in Node.js:

import crypto from 'crypto';

function verifyAyouneSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(',').map((kv) => kv.split('='))
  );
  if (!parts.t || !parts.v1) return false;
  const ageSec = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (ageSec > toleranceSec) return false; // replay window
  const expected = crypto
    .createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex'),
  );
}

Bis das Feature live ist, sichern Sie Ihre Webhooks per geheimem Query-Parameter oder Custom-Header (z. B. X-Webhook-Secret: …) ab — dasselbe Muster nutzen Stripe-, PayPal- und SumUp-Webhooks heute auf hooks.ayoune.app.