Webhooks

Configure your webhook endpoint in the getpeppr console under Settings → Webhooks. getpeppr will send a POST request to your endpoint for each event.

Requirements

• Your endpoint must accept POST requests with application/json body
• Respond with a 2xx status code within 5 seconds
• Use HTTPS in production

Platform accounts receive the legal_entity.* events above on the same endpoint delivery channel as invoice webhooks: signed with Getpeppr-Signature, retried automatically, and filterable with the same event subscriptions.

• subTenantId maps back to the externalSubTenantId you supplied when creating the customer.
• legalEntityId is the getpeppr legal entity id for follow-up API calls.
• status is one of verified, verification_failed, awaiting_authz, or active.
• environment tells you whether the transition happened in sandbox or production.

When a supplier on the Peppol network sends an invoice or credit note to one of your Legal Entities, getpeppr stores the document and dispatches one of these events:

• inbound.invoice.received — an invoice addressed to your Legal Entity arrived
• inbound.creditnote.received — a credit note addressed to your Legal Entity arrived

Document embed

The UBL XML content is embedded in the webhook payload as a base64-encoded string (field data.document.content). Documents larger than 512 KB are stored but not embedded: content will be null and contentOmittedReason will be "size". A retrieval API is planned for Phase 2.

Deduplication

Delivery is at-least-once. Deduplicate on data.receivedDocumentId — it is the stable idempotency key for inbound events: one received document, one id, however many times it is delivered. event.id only identifies a single delivery attempt of one outbox row and does not dedupe duplicates created by internal redelivery repair (the same document can arrive under different event.id values).

Here's a complete webhook handler using the SDK types. The WebhookEvent type ensures type safety for all event payloads.

Every webhook request contains a JSON body with the following structure:

• id — unique event ID (identifies one delivery; for inbound events deduplicate on data.receivedDocumentId instead)
• type — event type string
• data — event-specific payload
• createdAt — ISO 8601 timestamp

Every webhook request carries a Getpeppr-Signature header. Verify it on your endpoint to prove the request came from getpeppr and was not tampered with in transit.

The signing secret

Each endpoint you register gets its own signing secret (prefixed whsec_), shown once when you create it under Settings → Webhooks. Copy it then — it is masked on every later view, and secrets are not rotatable: to replace one, delete the endpoint and create a new one.

Signature format

The header value has the shape t={unix_seconds},s={hmac_sha256_hex}, for example t=1751458504,s=d9b60cb5…:

• t — Unix timestamp (in seconds) at which the event was signed
• s — the signature: HMAC-SHA256(secret, "{t}.{rawBody}"), hex-encoded

The signed message is the timestamp, a literal ., then the raw request body — exactly the bytes you received. Recompute the HMAC with your secret and compare it to s.

Verify with the SDK (recommended)

await webhooks.constructEvent(rawBody, signatureHeader, secret) from @getpeppr/sdk does everything in one call — header parsing, the HMAC, a constant-time comparison, and a 5-minute replay-tolerance check — and throws if any step fails. See the Handler Example above.

Verify without the SDK

Any language with an HMAC library can verify the signature. In Node.js:

import crypto from "node:crypto";

/** Verify an incoming getpeppr webhook. Throws if the signature is invalid. */
function verifyGetpepprSignature(
  rawBody: string,          // the exact raw request body (a string, NOT parsed JSON)
  signatureHeader: string,  // the Getpeppr-Signature header value
  secret: string,           // your endpoint's whsec_ signing secret
  toleranceSeconds = 300,
): unknown {
  const match = signatureHeader.match(/t=([^,]+),s=(.+)/);
  if (!match) throw new Error("Malformed Getpeppr-Signature header");
  const [, timestamp, received] = match;

  // Replay protection: reject events older than the tolerance window.
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(Number(timestamp)) || age > toleranceSeconds) {
    throw new Error("Timestamp outside tolerance");
  }

  // Recompute HMAC-SHA256 over "{timestamp}.{rawBody}" and compare in constant time.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");
  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) throw new Error("Invalid signature");

  return JSON.parse(rawBody); // safe to trust and parse now
}

Common pitfalls

• Hash the raw body — verify against the exact bytes received, before any JSON parsing. Re-serialising the parsed object (key order, whitespace) changes the HMAC and makes a valid signature look invalid. This is the most common cause of a false “invalid signature”.
• Keep your clock in sync — verification rejects events older than 5 minutes as replay protection, so a drifting server clock fails legitimate webhooks. Run NTP.
• Deduplicate — delivery is at-least-once. Use the stable resource key in data (for inbound events, data.receivedDocumentId); event.id identifies a single delivery attempt, not the document.
• Respond quickly — return 2xx within 5 seconds and process asynchronously; failed deliveries are retried with backoff.