---
title: "Pingen lifecycle callback"
method: POST
path: "/mh/pingen/webhook"
tags: ["Letters"]
---

# Pingen lifecycle callback

`POST /mh/pingen/webhook`

## Request

- Base URL: `https://api.vocal.email`
- URL: `https://api.vocal.email/mh/pingen/webhook`
- Auth: none required
- TypeScript: <https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api/docs/mh/pingen/webhook/post.ts> (a function with typed inputs; its response is checked against the schema)

Verifies a hex HMAC-SHA256 of the unchanged body and stores the event before acknowledging. Duplicate callbacks are accepted. Uses provider event time when included, otherwise callback creation time.

## Headers

- `Signature` string, required

## Request body

- object

## Response `200`

Event saved

- object
  - `data` object
    - `received` boolean
  - `success` boolean

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `403`: Invalid provider signature or organisation
- `404`: Resource not found
- `409`: Idempotency-Key reused with different content
- `413`: PDF exceeds 20 MB
- `500`: Persistence failure
- `502`: Submission could not be confirmed; check history before resending
- `503`: Provider/configuration unavailable

## Changes

- **2026-09-11** `f2a5ce43a2df`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api/changes/mh/pingen/webhook/post.md)

---

[API](https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api.md) - [All operations](https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api/revisions/d0319ad57804?raw)