Zum Hauptinhalt springen

Echtzeit-Webhooks für alle Events in deinem Business

COPE Webhooks liefern dir alle relevanten Business-Events in Echtzeit direkt in dein System – signiert, zuverlässig und mit vollständiger Entwicklungsunterstützung.

📄 Die vollständige Dokumentation findest du hier: [Webhooks overview - COPE]

COPE Webhooks beinhalten

  • HTTPS-only Endpoints

  • HMAC-SHA256 Signatur mit Anti-Replay-Schutz

  • CloudEvents 1.0 Payload-Standard

  • Automatische Retries mit Backoff

  • 90 Tage Event-Replay möglich

Ablauf:
COPE → Event → Dein Endpoint (Webhook)

Beispiel: Echtzeit-Webhook Payload

http

POST /your-endpoint HTTP/1.1 Content-Type: application/json Cope-Signature: t=1717499231,v1=a8c7b9...  {   "specversion": "1.0",   "type": "payment.sale.succeeded",   "source": "cope-payments",   "id": "evt_01HK9YJF...",   "time": "2026-06-04T13:42:11Z",   "subject": "ord_8s7xV2K",   "data": {     "order_id": "ord_8s7xV2K",     "business_uuid": "biz_a1b2c3",     "amount_total": 49700,     "currency": "USD"   } }

Events, die du abonnieren kannst

Webhooks (automatische Echtzeit-Benachrichtigung von COPE an dein System) sind pro Endpoint und pro Event-Typ konfigurierbar – du entscheidest, ob du alles empfängst oder nur gezielte Events.

Cart Events
​cart.created · cart.line.added · cart.line.updated · cart.line.removed · cart.buyer_identity.set · cart.currency.changed · cart.abandoned

Checkout Events
​checkout.created · checkout.cancelled · checkout.expired

Order Events
​order.created · order.completed · order.failed

Payment Events
​payment.sale.succeeded · payment.sale.failed · payment.refund.created · payment.refund.reversed

Disputes & Chargebacks
​payment.dispute.opened · payment.dispute.won · payment.dispute.lost · payment.dispute.counter_fee.created · payment.chargeback.created · payment.chargeback.reversed

Payouts
​payout.transfer.initiated · payout.transfer.completed

Ticketing
​ticketing.event.published · ticketing.check_in.created · ticketing.ticket.issued · ticketing.ticket.voided · ticketing.ticket.reissued

Webhook Lifecycle
​webhook.endpoint.created · webhook.endpoint.updated · webhook.endpoint.auto_disabled

Jedes Event verdeutlicht den Nutzungsfall.

CloudEvents 1.0 – ein Standard, den dein Stack versteht

Alle Webhook Payloads basieren auf CloudEvents 1.0 – ein einheitlicher, vorhersehbarer Envelope für alle Events.

Feld

Bedeutung

specversion

Immer 1.0

type

Event-Typ (z. B. payment.sale.succeeded)

source

Auslösender Service

id

Eindeutige Event-ID

time

Zeitpunkt im RFC3339 Format

subject

Primäre Ressource (z. B. Order ID)

data

Event-spezifische Payload

Wichtig – Idempotenz: Webhooks werden at-least-once geliefert. Events können mehrfach ankommen, die Reihenfolge ist nicht garantiert. Dedupliziere immer auf Basis von source + id.

Sicherheit – HMAC-SHA256 mit Anti-Replay

Jeder Webhook wird signiert, damit du sicherstellen kannst, dass er wirklich von COPE kommt.

Cope-Signature: t=timestamp,v1=hmac_signature

Die Signatur basiert auf timestamp.rawBody (HMAC-SHA256). Events älter als 5 Minuten werden automatisch abgelehnt.

Beispiel (Node.js):

js

import crypto from 'crypto';  function verifyCopeWebhook(rawBody, signatureHeader, secret) {   const parts = signatureHeader.split(',').reduce((acc, p) => {     const [k, v] = p.split('=');     acc[k] = v;     return acc;   }, {});    const timestamp = parseInt(parts.t, 10);   const signature = parts.v1;    const ageSeconds = Math.floor(Date.now() / 1000) - timestamp;   if (ageSeconds > 300) return false;    const expected = crypto     .createHmac('sha256', secret)     .update(`${timestamp}.${rawBody}`)     .digest('hex');    return crypto.timingSafeEqual(     Buffer.from(expected, 'hex'),     Buffer.from(signature, 'hex')   ); }

Wichtige Hinweise:

  • Jeder Endpoint (die URL-Adresse, an die COPE Daten sendet) hat ein eigenes Signing Secret ("Passwort")

  • Das Secret wird nur einmal bei Erstellung angezeigt

  • Rotation des Secrets erfolgt aktuell über einen neuen Endpoint

  • Secret niemals im Frontend verwenden

Delivery & Reliability

Retry-Schedule:

Versuch

Zeitabstand

1. Versuch

30 Sekunden

2. Versuch

5 Minuten

3. Versuch

30 Minuten

4. Versuch

2 Stunden

5. Versuch

12 Stunden

Maximum

6 Versuche

  • 5xx / Timeout → Retry

  • 4xx → kein Retry (Endpoint lehnt Event ab)

  • Dauerhafte Fehler → Auto-Disable des Endpoints

Wenn ein Endpoint dauerhaft fehlschlägt, wird er automatisch deaktiviert, ein webhook.endpoint.auto_disabled Event gesendet und du per E-Mail benachrichtigt.

Delivery-Garantie: At-least-once · Keine garantierte Reihenfolge · Idempotenz liegt bei dir (source + id)

Developer Tools

  • Test Events – synthetische Events triggern, die exakt wie echte Events signiert sind

  • Replay - einzelne Events oder Bulk Replay ab Zeitpunkt, bis zu 90 Tage in die Vergangenheit

  • Delivery Logs – Status Code, Antwortzeiten, Wiederholungsanzeige und Zeitstempel pro Zustellung

  • Endpoint Stats – Success Rate, p99 Latency, Event-Type Filter

Live vs. Roadmap

● Live:
HTTPS-only Webhooks · HMAC-SHA256 Signing + Anti-Replay · CloudEvents 1.0 · Retry System mit Backoff · At-least-once Delivery · Event Coverage (Cart, Checkout, Orders, Payments, Refunds, Disputes, Payouts) · Endpoint Management API · Test Events · Replay (90 Tage) · Delivery Logs & Stats

○ Roadmap:
Secret Rotation mit Grace Period · PII Redaction pro Endpoint · Native Zapier / Make / n8n Connectoren · Exactly-once / Ordered Delivery

Verwandte Artikel
Hat dies deine Frage beantwortet?