Webhooks

Registrera en HTTPS-endpoint så anropar pon dig när något händer — ingen polling-loop, inga bortkastade förfrågningar. Hantera webhooks på my.pon.app → Webhooks eller via API:et.

Topics

Prenumerera på det du faktiskt behöver. Ett valfritt listIds-filter (upp till 50, bara dina egna listor — okända id:n svarar 400 med invalidListIds) begränsar leveranserna till specifika listor.

Registrera

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 innehåller din signeringshemlighet (whsec_…) — den visas en enda gång. Registrerar du samma URL igen uppdateras prenumerationen och hemligheten behålls. Upp till 5 webhooks per konto.

Leveranser

Varje leverans är en POST med headrarna PON-Event: <topic> och PON-Signature: sha256=<hmac>:

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

Leveranserna är best-effort utan retries — om din endpoint ligger nere kommer nästa event (eller en hämtning från din sida) ikapp åt dig. Redirects följs inte. Flera matchande ändringar i samma skrivning slås ihop till en leverans per prenumererat topic.

Verifiera signaturen

Beräkna en HMAC-SHA256 över den råa request-kroppen med din hemlighet och jämför den — i konstant tid — med headern:

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

Ett 2xx kvitterar en leverans. Efter 20 misslyckanden i rad (allt annat, inklusive timeouts) pausas webhooken automatiskt (status: paused, pausedReason: auto_failures). Laga din endpoint och återaktivera sedan på my.pon.app eller via PATCH /v3/webhooks/{id} med { "status": "active" } — återaktivering nollställer räknaren. En manuell testping är POST /v3/webhooks/{id}/pings (räknas aldrig som ett misslyckande).