Zum Inhalt springen

Webhooks

Ein Webhook ist eine HTTP-Anfrage, die Invoise an Ihren Server sendet, wenn sich eine Zahlung ändert. Sie können mit GET-Statusprüfungen beginnen und Webhooks hinzufügen, wenn Sie automatische Updates benötigen.

Terminal-Fenster
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
-H 'Authorization: Bearer ivk_...' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Verwenden Sie Ihre eigene öffentliche HTTPS-URL. Lokale und private Adressen werden abgelehnt. Speichern Sie das beim Erstellen des Endpunkts zurückgegebene secret: Sie benötigen es, um Anfragen zu verifizieren.

Ein Shop kann bis zu 10 Endpunkte haben. Die URL eines Endpunkts kann geändert werden, verwenden Sie also einen weiter, statt einen weiteren hinzuzufügen. Siehe Limits.

Ereignis Bedeutung
transfer.observed Ein Transfer wurde gesehen; er ist noch nicht bestätigt.
transfer.confirmed Ein eingehender Transfer hat genügend Bestätigungen. Es kann nur eine teilweise Rechnungszahlung sein.
transfer.reverted Ein vorheriges Transfer-Ereignis wurde zurückgenommen.
invoice.closed Die Rechnung wurde on-chain abgeschlossen.
invoice.cancelled Die Zahlungsseite wurde storniert oder die Rechnung ist abgelaufen; dies ist keine Rückerstattung.
payout.sent Die Auszahlung wurde gesendet oder ihr ausgehender Transfer wurde gesehen.
payout.confirmed Eine vollständige Abrechnungsbuchung ist verfügbar.
payout.reverted Eine vorherige Auszahlungsbestätigung wurde zurückgenommen.
payout.failed Ein endgültiger Auszahlungsfehler erfordert ein Eingreifen.

Bei invoice.cancelled gibt data.reason den Grund an: expired, wenn die Rechnungslaufzeit abgelaufen ist, merchant_blocked, wenn das Invoise-Team den Händler gesperrt hat. Eine Stornierung durch den Händler, auch durch das Archivieren des Shops, hat keinen reason.

Eine leere filters-Liste empfängt alle Ereignisse. Andernfalls geben Sie Gruppen (transfer, invoice, payout), einzelne Ereignistypen wie payout.confirmed oder beides an. Eingehende Transfers und ausgehende Auszahlungen sind unterschiedliche Ereignisse. Eine vorübergehende RPC- oder Gas-Verzögerung ist kein payout.failed.

gas.wait und sweep.failed werden als Filter akzeptiert, aber Invoise sendet sie nicht an Ihren Endpunkt. Es sind interne Signale: gas.wait bedeutet, dass eine Auszahlung auf Mittel für die Netzwerkgebühr wartet und von selbst fortfährt; sweep.failed bedeutet, dass ein Versuch, die Mittel zu Ihrem Empfänger zu bewegen, fehlgeschlagen ist. Für keines von beidem ist eine Aktion Ihrerseits nötig. Eine Auszahlung, die nicht abgeschlossen werden kann, erreicht Sie als payout.failed.

In einem Sandbox-Shop können Sie beides über POST /shops/{shop_id}/sandbox/simulate simulieren, um zu prüfen, dass eine verzögerte Auszahlung Ihren Ablauf nicht stört. Sie ändern nur den Zustand der Auszahlung und senden keinen Webhook.

Invoise-Signature hat die Form t=<timestamp>,v1=<hex>. Die Signatur ist HMAC-SHA256 von timestamp + "." + raw_body, unter Verwendung Ihres Webhook-Secrets.

Das folgende Node.js-Beispiel lehnt außerdem Zeitstempel ab, die mehr als fünf Minuten von der Serveruhr abweichen. Halten Sie diese Uhr synchronisiert und wählen Sie Ihre Toleranz bewusst.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!match) return false;
const [, timestamp, signature] = match;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

Übergeben Sie die ursprünglichen Anfrage-Bytes als rawBody. Parsen Sie das JSON nicht und wandeln Sie es nicht wieder in einen String um, bevor Sie die Signatur prüfen. Lehnen Sie ungültige Signaturen ab, bevor Sie ihren Inhalt speichern oder darauf reagieren.

So sieht ein transfer.confirmed-Body aus. Das Schema jedes Ereignisses steht im Abschnitt webhooks von openapi.json.

{
"id": "<event-id>",
"type": "transfer.confirmed",
"created_at": "2026-09-19T10:00:05Z",
"data": {
"issuance_id": "<issuance-id>",
"public_id": "<public-id>",
"shop_id": "<shop-id>",
"external_id": "customer-42",
"type": "deposit",
"family": "evm",
"chain_id": 8453,
"token": "<token-address>",
"token_decimals": 6,
"address": "<payment-address>",
"recipient": "<recipient-address>",
"invoice_cancelled": false,
"cancelled_at": null,
"direction": "incoming",
"chain_event": {
"event_id": "<transfer-id>",
"kind": "transfer.confirmed",
"chain_id": 8453,
"tx_hash": "<tx-hash>",
"log_index": 2,
"block_number": 35123456,
"block_hash": "<block-hash>",
"token": "<token-address>",
"from": "<payer-address>",
"to": "<payment-address>",
"amount": "25000000",
"confirmations": 12,
"occurred_at": "2026-09-19T10:00:00Z"
}
}
}

Um eine Zahlung gutzuschreiben, lesen Sie data.chain_event. amount ist der eingegangene Betrag in Basiseinheiten des Tokens: Teilen Sie ihn durch 10^data.token_decimals, 25000000 bei 6 Dezimalstellen sind also 25 Token. event_id identifiziert den Transfer, tx_hash ist seine Transaktion. data.issuance_id und data.external_id nennen die Rechnung oder Einzahlung, die er bezahlt hat. Bei einer Rechnung kann ein Transfer eine Teilzahlung sein.

Fall Behandlung
Duplikate Deduplizieren Sie anhand von Invoise-Event-ID, die der id der Envelope entspricht. Speichern Sie die ID und das Geschäfts-Update atomar.
Ein Ereignis annehmen Speichern Sie angenommene Ereignisse dauerhaft, geben Sie umgehend 2xx zurück und verarbeiten Sie anschließend die Warteschlange.
Wiederholungen und Replays Wiederholungen und manuelle Replays verwenden dieselbe Ereignis-ID erneut. Invoise-Attempt-ID ändert sich und ist kein Deduplizierungsschlüssel.
Header Jede Anfrage enthält Invoise-Event-ID und Idempotency-Key, beide gleich der Ereignis-id; Invoise-Delivery-ID, eine pro Ereignis und Endpunkt; Invoise-Attempt-ID, bei jedem Versuch neu; und Invoise-Signature.
Ereignisreihenfolge Ereignisse können in falscher Reihenfolge eintreffen. Verwenden Sie deren Inhalt und gleichen Sie bei Bedarf mit dem aktuellen Status ab.

Entfernt eine Reorganisation der Chain einen Transfer, kommt transfer.reverted, dessen chain_event.reference_event_id gleich der event_id des gutgeschriebenen Transfers ist: Buchen Sie diesen Betrag zurück. payout.confirmed enthält amount, den Betrag, den der Empfänger erhalten hat, und service_fee, die Gebühr dieser Auszahlung; in payout.sent und payout.failed sind beide null. Jedes Auszahlungsereignis hat eine stabile payout_id und den Transaktions-Hash. incoming_transfer_ids listet die Transfers, die die Auszahlung abdeckt, höchstens 100; incoming_transfers_truncated markiert eine längere Liste.

Ältere gespeicherte Ereignisse können project_id verwenden; lesen Sie zuerst shop_id und greifen Sie bei Bedarf darauf zurück. Replays behalten die ursprünglichen Bytes.

GET /api/v1/shops/{shop_id}/deposits ist das vollständige Journal der bestätigten eingehenden Transfers des Shops, für Rechnungen wie für Einzahlungen, die neuesten zuerst. Es ist keine Adressliste: POST auf denselben Pfad erstellt eine Einzahlungsadresse. Jede Zeile hat id, gleich chain_event.event_id aus dem Webhook, sowie issuance_id, external_id, amount, tx_hash, sender und occurred_at. Blättern Sie mit limit und cursor darin, um nach einem Ausfall aufzuholen oder Ihre Buchungen zu prüfen.

status ist im Journal immer confirmed. Ein durch eine Reorganisation rückgängig gemachter Transfer verschwindet aus dem Journal, und Sie erhalten dafür transfer.reverted.

Eine Zustellung gilt als erfolgreich, wenn Ihr Endpunkt mit einem beliebigen 2xx-Status antwortet. Ein anderer Status, ein Timeout oder ein Verbindungsfehler wird wiederholt: der erste Versuch nach 5 Sekunden, danach verdoppelt sich die Wartezeit nach jedem Versuch bis auf höchstens eine Stunde zwischen den Versuchen. Kommt 72 Stunden lang keine 2xx-Antwort, hört Invoise auf und markiert die Zustellung als failed.

Jeder Versuch hat insgesamt 20 Sekunden, und Ihre Antwort-Header müssen innerhalb von 10 Sekunden ankommen. Speichern Sie das Ereignis und antworten Sie zuerst; die Arbeit erledigen Sie danach.

Das Archivieren eines Shops mit PATCH /api/v1/shops/{shop_id} und {"archived":true} deaktiviert seine Webhook-Endpunkte. Die Ereignisse des Shops, auch das invoice.cancelled seiner unbezahlten Rechnungen, werden weiter aufgezeichnet, aber nicht zugestellt.

Listen Sie mit GET /api/v1/shops/{shop_id}/deliveries auf. Wiederholen Sie eine Zustellung mit POST /api/v1/shops/{shop_id}/deliveries/{id}/replay und einem gespeicherten Idempotenzschlüssel. Das Wiederholen erstellt kein neues Geschäftsereignis. Ein Replay startet ein neues 72-Stunden-Fenster für Wiederholungen; zugestellte und fehlgeschlagene Zustellungen lassen sich wiederholen.