Webhooks

Configure your webhook endpoint in the getpeppr console under Developer → 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
• Your endpoint URL must use https://, in sandbox and in production — payloads can carry invoice data, so plain http:// URLs are rejected when you save them and never receive a delivery

How many endpoints, and which environment

How many endpoints you can save depends on your plan, per environment: 1 on Sandbox, 3 on Starter, 5 on Pro, 10 on Business, and 5 on a Platform account. An endpoint that receives both environments counts against both.

Each endpoint receives both sandbox and production events unless you scope it. Set Environment to Sandbox only or Production only in the console, and that endpoint receives nothing from the other one — which is how you point a staging server at getpeppr without it receiving your customers' production documents. A new endpoint receives both environments until you choose.

A scoped endpoint also receives nothing when an event carries no environment at the root (older queued events, and status events whose environment is not resolved yet). Leave an endpoint unscoped if you want those. The test.ping you send from the console is not affected: it goes to the endpoint you asked it for, whatever its scope.

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

legal_entity.registered is receive-readiness proof: it fires only after the public SML → SMP → Invoice metadata → active AS4 path succeeds. Identity verification and Storecove registration alone do not emit it. Its status is active, or no_registry for the sandbox registryless test scheme. Outbound sending remains independent and keeps its existing gates.

• 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, no_registry, unsupported_scheme, verification_failed, registration_failed, awaiting_authz, awaiting_release, or active.
• reason is present on failures. For registration_failed it is already_registered, invalid_format, or provider_error, matching the current Legal Entity's registrationDetail.reason.
• heldBy is present on legal_entity.awaiting_release when known: the SMP host of the access point that still holds the address.
• 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, up to the 10 MiB storage limit, are stored but not embedded: content will be null and contentOmittedReason will be "size". Fetch those — and any document you did not persist — with GET /v1/received-documents/{id}/as/xml, which returns the original UBL byte for byte. Use data.receivedDocumentId as the id.

We keep the original for 90 days after receipt, or until a Platform contract's exit window closes if that comes first. After that the download answers 410 Gone (received_documents.xml_expired); the document's details stay listed. getpeppr is not an archive: store the original on your side when it reaches you.

Documents we cannot deliver

When a document arrives for your account but getpeppr cannot deliver it to you, you receive inbound.document.undeliverable instead of inbound.*.received. There is no received document behind it: no receivedDocumentId, and nothing to fetch from /v1/received-documents. It does not count toward your usage.

In the dashboard, the document appears on the Invoices page with the status Undeliverable, with its own detail page, and as a failed entry in Activity. Both show the result code and the sentence above. The Invoices page shows the 500 most recent of them; past that, it says how many more there are.

{
  "id": "evt_0a1b2c3d4e5f6071",
  "type": "inbound.document.undeliverable",
  "environment": "production",
  "data": {
    "undeliverableDocumentId": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a99",
    "providerDocumentId": "storecove-guid-def456",
    "reason": "too_large",
    "environment": "production",
    "legalEntityId": "7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b",
    "externalSubTenantId": "customer_be_001",
    "documentType": "invoice",
    "sender": {
      "peppolId": "0208:0123456789",
      "name": "Supplier SA"
    },
    "invoiceNumber": "INV-456",
    "receivedAt": "2026-09-15T08:00:00.000Z",
    "sizeBytes": null,
    "storageLimitBytes": 10485760
  },
  "createdAt": "2026-09-15T08:00:01.000Z"
}

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 is stable per received document too, but it lives in our delivery outbox, whose delivered and failed rows are purged after 90 days — receivedDocumentId is the key that survives that purge.

Where sender comes from. Both fields are read from the supplier party the document names for itself — cac:AccountingSupplierParty/cac:Party, its cbc:EndpointID and that element's schemeID — and from nowhere else. It is what the document claims, which for a conformant Billing message is the same identifier the envelope was sent under (rule BR-SBDH-2), but we publish the document's claim, not the transport identity.

We never guess it. If the document does not state a supplier endpoint unambiguously, both fields are null rather than filled from what our provider knows about the sender — an identifier you reconcile a supplier on is worth nothing if it might be a guess. A conformant Peppol document always states it (cbc:EndpointID is mandatory, with a mandatory schemeID), so in practice null means a document that did not come through the network or that we could not read. On inbound.document.undeliverable with reason: "too_large" the document is never parsed at all, so sender there is always null; use providerDocumentId to trace it.

The scheme is the numeric EAS code when it is in the CEF EAS code list, and the scheme as declared otherwise. to.peppolId accepts both that code and the scheme's symbolic alias, so compare the two canonically rather than as raw strings.

Here's a complete webhook handler using the SDK types. WebhookEvent types the envelope (id, type, createdAt); data is unknown, so narrow it per event.type as the example does.

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

• id — event ID, the same for every endpoint and every retry of that event (for inbound events deduplicate on data.receivedDocumentId instead)
• type — event type string
• environment — "sandbox" or "production": the business environment of the resource this event is about. Read it after verifying the signature, then call the API with the matching key (sk_sandbox_* / sk_live_*). The field is optional by contract, for three reasons: events emitted before it existed are still replayed verbatim, test.ping — a synthetic event tied to no resource — deliberately carries none, and a status event whose submission environment is not yet resolved transiently carries none either (the field appears on the next event once resolution lands). Absence never means “production by default” — treat “no field” as “not yet known”. When present, the value is exact, never guessed.
• 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 Developer → 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 the event, and the log that holds it is purged after 90 days.
• Respond quickly — return 2xx within 5 seconds and process asynchronously; failed deliveries are retried with backoff.