Webhooks

Coinetic meldet Ihrem Server Änderungen an einer Rechnung per POST-Anfrage. Ein Webhook ist ein Signal „Rechnung prüfen“, kein Zahlungsnachweis.

Einrichtung

• Dashboard → „Schlüssel und Webhooks“ → „Hinzufügen“. Die URL muss https:// auf eine öffentliche Adresse und Port 443 sein (in der Sandbox zusätzlich http://localhost).
• Das Endpoint-Secret wird einmal angezeigt. Bis zu 5 aktive Endpoints: Jedes Ereignis geht an alle.

Anfrage

POST /webhooks/coinetic HTTP/1.1
Content-Type: application/json
User-Agent: cryptopay-webhooks/1
X-Webhook-Id: evt_3f9c…
X-Webhook-Timestamp: 1760000000
X-Webhook-Signature: v1=5d1e…

{"id":"evt_3f9c…","type":"invoice.paid","created_at":"2026-10-12T15:04:05Z","livemode":true,"data":{"invoice_id":"inv_x7k2…","order_id":"ORDER-1001","status":"paid","paid_amount":"49990000"}}

X-Webhook-Id bleibt bei Wiederholungen gleich. Während einer Secret-Rotation enthält X-Webhook-Signature zwei Signaturen, durch Komma getrennt. Technische Namen (cryptopay-webhooks/1) sind historisch bedingt – Sie müssen bei sich nichts ändern.

Signatur prüfen

expected = "v1=" + hex(HMAC-SHA256(webhook_secret, X-Webhook-Timestamp + "." + raw_body))

1. Nehmen Sie den rohen Body – die Bytes vor dem JSON-Parsing.
2. Prüfen Sie, dass X-Webhook-Timestamp höchstens 5 Minuten von der aktuellen Zeit abweicht.
3. Teilen Sie X-Webhook-Signature am Komma. Die Signatur ist gültig, wenn irgendein Teil mit dem erwarteten Wert übereinstimmt (Vergleich in konstanter Zeit).
4. Keine Übereinstimmung – antworten Sie mit 401 und tun Sie nichts weiter.

Referenz: Secret whsec-0123456789abcdef0123456789abcdef, Timestamp 1760000000, Body {"id":"evt_1","type":"invoice.paid"} → v1=aceeb56215ba09e7a2923d48f89afb8331f422f2d0a8cf60f76fef69fe06a6a4.

Verarbeitung

Signatur prüfen → Deduplizierung über X-Webhook-Id → GET /v1/invoices/{invoice_id}
→ Bestellung nach Status aus der API aktualisieren (genau einmal ausliefern) → mit 2xx antworten

• Deduplizierung. Ein Ereignis kann mehrfach eintreffen. Speichern Sie verarbeitete X-Webhook-Id; setzen Sie das Flag „ausgeliefert“ in derselben Transaktion wie die Auslieferung.
• Antworten Sie schnell – innerhalb von 10 Sekunden. Längere Arbeit gehört in eine Queue.
• Antwortcodes: 2xx – angenommen; 410 Gone – diese Zustellung nicht wiederholen; jeder andere Code (auch 3xx – Redirects werden nicht verfolgt) oder ein Timeout – Wiederholung.
• Ignorieren Sie unbekannte Felder und Ereignistypen – die Liste wird wachsen.

Fertige Handler in vier Sprachen finden Sie im Schnellstart.

Wiederholungen

10 s → 30 s → 2 Min. → 10 Min. → 30 Min. → 1 h → 3 h ×7 → 1 h, mit leichter Streuung. Der letzte Versuch erfolgt nach etwa 24 Stunden. Eine fehlgeschlagene Zustellung können Sie erneut senden: Dashboard → „Webhooks“ → „Erneut senden“.

Reihenfolge

Ereignisse einer Rechnung werden in Reihenfolge an einen Endpoint zugestellt: Das nächste geht erst raus, wenn die vorherige Zustellung nicht mehr auf eine Wiederholung wartet. Ob sie erfolgreich war oder nicht – danach folgen die nächsten. Verlassen Sie sich deshalb auf den Status aus GET /v1/invoices/{id}, nicht auf die Reihenfolge der Ereignisse. Ereignisse verschiedener Rechnungen sind unabhängig.

Ereignistypen

Abrechnungsereignisse (billing.*) betreffen die Gebührenrechnungen der Plattform: gestellt, bezahlt, überfällig, Sperre und deren Aufhebung.

Secret-Rotation

Dashboard → „Secret ändern“: Coinetic signiert ab dann mit beiden Secrets.

1. Hinterlegen Sie das neue Secret auf dem Server (akzeptieren Sie beide).
2. Klicken Sie auf „Rotation abschließen“ – das alte wird gelöscht.
3. Entfernen Sie das alte Secret vom Server.