Webhooki API resellera

Zdarzenia webhooków, payloady, weryfikacja podpisu HMAC w Pythonie i Node, ponowienia z backoffem, zasady bezpieczeństwa URL i deduplikacja po id zdarzenia.

Utworzenie webhooka

POST /webhooks (uprawnienie webhooks): adres URL tylko https i niepusta lista zdarzeń. Najwyżej 5 webhooków. Opcjonalny Idempotency-Key: powtórzenie zwraca ten sam webhook, bez sekretu. last_delivered_at to czas ostatniej odpowiedzi 2xx twojego serwera (null, dopóki żadnej nie było).

curl -s -X POST https://app.oneprovider.dev/partner/v1/webhooks \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://shop.example.com/op-webhook","events":["order.completed","balance.low"]}'

{
"id": "<webhook id>",
"url": "https://shop.example.com/op-webhook",
"events": ["order.completed", "balance.low"],
"active": true,
"secret_last4": "a1b2",
"created_at": "2026-10-08T12:00:00Z",
"last_delivered_at": null,
"secret": "whsec_..."
}

Zdarzenia

Dane zdarzenia nigdy nie zawierają sekretów: kluczy, tokenów ani kodów. Test (POST /webhooks/{id}/test) wysyła zdarzenie serwisowe webhook.test z danymi {"message": "test"}; nie można go subskrybować.

Żądanie i podpis

Wysyłamy POST z treścią w formacie JSON:

{
"id": "evt_...",
"type": "order.completed",
"created_at": "2026-10-08T12:00:00Z",
"data": {
"order_id": 42,
"external_order_id": "shop-1042",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00"
}
}

Treść jest wysyłana jako zwarty JSON z kluczami w kolejności alfabetycznej; weryfikuj podpis na bajtach dokładnie w takiej postaci, w jakiej dotarły, a nie na ponownie zbudowanym JSON.

v1 to zapis szesnastkowy HMAC-SHA256, w którym kluczem jest sekret webhooka (whsec_...), a wiadomością ciąg "<t>" + "." + raw_body.

Weryfikacja podpisu

1. Odczytaj surową treść żądania: podpis obejmuje dokładne bajty, ponownie zserializowany JSON się nie zgodzi.
2. Przelicz HMAC i porównaj go z v1 w stałym czasie (hmac.compare_digest, timingSafeEqual).
3. Odrzuć żądanie, jeśli |now - t| przekracza 5 minut, aby nie dało się odtworzyć starego podpisu.
4. Odpowiadaj szybko 2xx (limit czasu to 10 sekund), a ciężką pracę wykonuj asynchronicznie.

Python

import hashlib
import hmac
import time
TOLERANCE = 300 # seconds
def verify(secret: str, header: str, raw_body: bytes) -> bool:
"""header is X-OP-Signature: t=<unix>,v1=<hex>; raw_body is the unparsed request body."""
parts = dict(p.strip().partition("=")[::2] for p in header.split(","))
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > TOLERANCE:
return False
signed = t.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)

import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRET = os.environ["OP_WEBHOOK_SECRET"] # whsec_...
seen: set[str] = set() # use a database table with a unique index in production
@app.post("/op-webhook")
async def op_webhook(request: Request):
raw = await request.body() # the raw bytes, before any JSON parsing
if not verify(SECRET, request.headers.get("X-OP-Signature", ""), raw):
raise HTTPException(status_code=400, detail="bad signature")
event = json.loads(raw)
if event["id"] in seen: # retries resend the same event id
return {"ok": True}
seen.add(event["id"])
if event["type"] == "order.completed":
... # your logic
return {"ok": True} # any 2xx marks the event as delivered

Node.js

import crypto from "node:crypto"
import express from "express"
const SECRET = process.env.OP_WEBHOOK_SECRET // whsec_...
const TOLERANCE = 300 // seconds
const seen = new Set() // use a database table with a unique index in production
function verify(secret, header, raw) {
const parts = Object.fromEntries(
String(header).split(",").map((p) => p.trim().split("=")),
)
const t = Number(parts.t)
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE) return false
const expected = crypto
.createHmac("sha256", secret)
.update(parts.t + ".")
.update(raw)
.digest("hex")
const a = Buffer.from(expected)
const b = Buffer.from(parts.v1 ?? "")
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
const app = express()
// express.raw keeps the body as a Buffer: do not use express.json() on this route
app.post("/op-webhook", express.raw({ type: "application/json" }), (req, res) => {
if (!verify(SECRET, req.get("X-OP-Signature"), req.body)) return res.sendStatus(400)
const event = JSON.parse(req.body.toString("utf8"))
if (!seen.has(event.id)) {
seen.add(event.id) // retries resend the same event id
if (event.type === "order.completed") {
// your logic
}
}
res.sendStatus(200) // any 2xx marks the event as delivered
})
app.listen(3000)

Ponowienia

Za dostarczoną uznawana jest tylko odpowiedź 2xx. Wszystko inne (także 3xx, bo przekierowania nie są śledzone, a także przekroczenia czasu i błędy połączenia) jest ponawiane z wykładniczym backoffem: 1 minuta, 2, 4 i tak dalej, maksymalnie 4 godziny, aż do 24 godzin po zdarzeniu; potem dostarczenie przechodzi w stan failed. Każde ponowienie niesie to samo id zdarzenia, więc deduplikuj po nim: przetworzone id trzymaj w tabeli z unikalnym indeksem.

Zasady dla URL

• Tylko https, port 443 (każdy inny port to 400 invalid_url) i nazwa hosta; adresy IP są odrzucane. URL ma najwyżej 500 znaków ASCII, bez nazwy użytkownika, hasła i fragmentu.
• Żaden adres, na który rozwiązuje się nazwa, nie może być prywatny, pętli zwrotnej, link-local ani zarezerwowany.
• Sprawdzenie odbywa się przy utworzeniu i przy każdym dostarczeniu. Naruszenie przy utworzeniu daje 400 invalid_url.

Test i dziennik

curl -s -X POST https://app.oneprovider.dev/partner/v1/webhooks/<webhook id>/test -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/webhooks/<webhook id>/deliveries?limit=20" -H "Authorization: Bearer $OP_PARTNER_TOKEN"

Obiekt dostarczenia: id, event_id, event, status (pending, delivered, failed), attempts, next_attempt_at, last_error (http_<status>, timeout, blocked_address lub nazwa błędu połączenia), last_status (status HTTP, którym odpowiedział twój serwer, null, gdy nie odpowiedział), last_body (początek odpowiedzi, do 300 znaków, w jednej linii), created_at. Usunięcie webhooka: DELETE /webhooks/{id}. Testy i ręczne ponowienia (w Panelu) są razem ograniczone do 6 na minutę; ponowić można tylko niedostarczone zdarzenie, dla dostarczonego odpowiedź to 409 already_delivered. Ręczne ponowienie jest dostępne tylko w Panelu, nie z tokenem.