Create and manage Webhooks

Pingen offers automatic notifications via webhooks for important events. For example, you are notified in real time as soon as a letter has been sent, has a problem or was reported as undeliverable. This allows you to execute further actions automatically without having to actively "poll" the Pingen API for changes.

Create Webhooks

Webhooks can be created directly in the Pingen WebApp via the menu item "Organisation Administration" --> "Webhooks" by clicking on the "Add your first Webhook" button.

Next, the desired event category for the webhook must be selected. Pingen offers the following event categories:

• Letter Issues : Any events related to issues sending a letter. Usually related to issues processing the letter like for example: if a PDF is not in format A4, if a PDF has content in the Restricted Areas, if there are insufficient Credits available etc.
• Sent Letters: Any events related to postal delivery like for example: if a letter has been forwarded to the post or if a postal tracking ID has been received
• Undeliverable Letters: Any events related to information if and why a letter could not be delivered by the post

As soon as an event category has been selected, the Webhook URL (URL to which Pingen should send the webhooks) and a signature Signature Secret must be specified. For the Webhook URL, it is essential that it can be reached on port 443. The Secret is used to ensure that only data from trustworthy sources is processed. Any character string (max. 32 characters) can be used as a Secret. If you specify a Secret, make sure that this value is validated when processing the webhooks.

Manage Webhooks

The webhook administration can be opened directly in the Pingen WebApp via the menu item "Manage organization" --> "Webhooks" by clicking on the respective webhook:

The webhooks administration provides an overview of all requests sent so far. Furthermore, in the top right-hand corner you can also send a Test Webhook request as well as Resend Failed Requests.

The overview displays the most important information as well as the status of the request. Requests can have the following statuses:

• Success: Webhook was successfully delivered
• Retry: Webhook has not yet been successfully delivered. However, Pingen retries the delivery up to 7 times
• Failed: Webhook could not be delivered successfully even with the retries

By clicking on a request, the details view of the respective request can be opened:

In the details view, you can see both the content of the request as well as the respective response from the target URL. Webhooks with the status "Failed" can also be resent directly via the link in the sidebar.

Delete Webhooks

Webhooks can be deleted directly in the Pingen WebApp via the menu item "Organisation Administration" --> "Webhooks". Simply move the mouse over the desired webhook and click on the recycle bin icon: