Webhooks

Registrer et HTTPS-endepunkt, så kaller pon deg når noe skjer — ingen polling-løkke, ingen bortkastede requests. Administrer webhooks på my.pon.app → Webhooks eller via API-et.

Topics

Abonner på det du faktisk trenger. Et valgfritt listIds-filter (opptil 50, kun dine egne lister — ukjente id-er svarer 400 med invalidListIds) avgrenser leveransene til bestemte lister.

Registrer

POST /v3/webhooks

curl -X POST https://api.pon.app/v3/webhooks \
  -H "Authorization: Bearer pon_pat_XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/pon",
        "events": ["item.checked"],
        "listIds": ["LIST_ID"] }'

Svaret inneholder signeringshemmeligheten din (whsec_…) — vist én gang. Registrerer du samme URL på nytt, oppdateres abonnementet og hemmeligheten beholdes. Opptil 5 webhooks per konto.

Leveranser

Hver leveranse er en POST med headerne PON-Event: <topic> og PON-Signature: sha256=<hmac>:

{ "event": "item.checked", "listId": "6led…", "cursor": 123, "at": "2026-08-09T19:00:00.000Z" }

Leveranser er best-effort uten retries — er endepunktet ditt nede, tar neste event (eller en fetch fra din side) deg à jour. Redirects følges ikke. Flere matchende endringer i én skriving koaleseres til én leveranse per abonnert topic.

Verifiser signaturen

Beregn en HMAC-SHA256 over den rå request-bodyen med hemmeligheten din og sammenlign den — i konstant tid — med headeren:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = "sha256=" +
    createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    header.length === expected.length &&
    timingSafeEqual(Buffer.from(header), Buffer.from(expected))
  );
}

import hashlib, hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(header, expected)

Circuit breaker

En 2xx kvitterer for en leveranse. Etter 20 feil på rad (alt annet, inkludert timeouts) pauser webhooken seg selv (status: paused, pausedReason: auto_failures). Fiks endepunktet ditt, og reaktiver så på my.pon.app eller via PATCH /v3/webhooks/{id} med { "status": "active" } — reaktivering nullstiller telleren. Et manuelt test-ping er POST /v3/webhooks/{id}/pings (teller aldri som feil).