HMAC-signierte Webhooks für den Off-Ramp-Lebenszyklus.
Wenn Ihr Produkt asynchronen Lifecycle-Status benötigt, registrieren Sie Webhook-Endpunkte und verifizieren Sie jede Zustellung. Die Signatur bindet den Zeitstempel an den exakten Rohkörper, damit Sie manipulierte oder wiederholte Payloads ablehnen können.
Lifecycle-Ereignisse
| Ereignis | Bedeutung |
|---|---|
| deposit.created | Eine Verkäufereinzahlung wurde auf Base erstellt |
| deposit.partially_filled | Eine Einzahlung wurde teilweise gefüllt |
| deposit.filled | Eine Einzahlung wurde vollständig gefüllt |
| deposit.closed | Ein Verkäufer hat das verbleibende Guthaben geschlossen oder abgehoben |
| otc.taken | Eine private OTC-Einzahlung wurde vom genehmigten Käufer in Anspruch genommen |
Jede Zustellung verifizieren
- 1Lesen Sie den X-Usdctofiat-Signature-Header im Format t=<unix>,v1=<hex>.
- 2Erstellen Sie die signierte Nutzlast als String timestamp.rawBody unter Verwendung des rohen, ungeparsten Körpers.
- 3Berechnen Sie HMAC-SHA256 über diese Nutzlast mit Ihrem Endpunkt-Secret.
- 4Vergleichen Sie in konstanter Zeit mit dem v1-Hex-Wert, bevor Sie dem Ereignis vertrauen.
- 5Lehnen Sie optional Zustellungen ab, deren Zeitstempel älter als Ihr gewähltes Zeitfenster ist.
Replay-Schutz liegt in Ihrer Verantwortung
Der Referenzempfänger im Starter-Repository behandelt Zeitstempel, die älter als 5 Minuten sind, als veraltet, um sich gegen Replays zu schützen. Dieses Zeitfenster wird von Ihrem Verifier durchgesetzt, nicht vom Sender, sodass Sie es entsprechend Ihrer Latenz und Wiederholungstoleranz anpassen können.
Da die Signatur timestamp.rawBody abdeckt, parsen Sie das JSON erst, nachdem die HMAC-Prüfung bestanden hat. Das Verifizieren des geparsten Objekts anstelle der Rohbytes ist der häufigste Weg, die Signaturverifizierung subtil falsch zu implementieren.
Registrieren und betreiben
- Registrieren Sie Endpunkte mit Ihrem Peerlytics API-Schlüssel; ein Schlüssel authentifiziert die Off-Ramp- und Peerlytics-Oberflächen.
- Endpunkte, die wiederholt aufeinanderfolgende Zustellungsfehler aufweisen, können deaktiviert werden, bis Sie das Problem beheben.
- Verwenden Sie den Empfänger im Starter-Repository als bewährte HMAC-Verifizierungsreferenz.
- Behandeln Sie Webhooks als Zustandshinweise; gleichen Sie bei Bedarf mit der Onchain-Wahrheit über deposits() ab.
Keep exploring
Common questions
Wie werden USDCtoFiat-Webhooks signiert?
Jede Zustellung enthält X-Usdctofiat-Signature: t=<unix>,v1=<hex>, einen HMAC-SHA256 über den String timestamp.rawBody. Berechnen Sie den HMAC mit Ihrem Endpunkt-Secret über den Rohkörper neu und vergleichen Sie in konstanter Zeit, bevor Sie dem Ereignis vertrauen.
Wie verhindere ich wiederholte Webhooks?
Lehnen Sie Zustellungen ab, deren signierter Zeitstempel älter als ein von Ihnen gewähltes Zeitfenster ist. Der Referenzempfänger verwendet 5 Minuten. Der Sender erzwingt kein Zeitfenster; dies liegt in der Verantwortung Ihres Verifiers.
Benötige ich einen API-Schlüssel für Webhooks?
Ja. Das Erstellen von Einzahlungen ist permissionslos, aber die Registrierung von Webhook-Endpunkten erfordert einen Peerlytics API-Schlüssel. Derselbe Schlüssel authentifiziert auch die Peerlytics API.