What does the postback service do?
The Signhost postback service provides real-time updates on transactions. Do not use active polling (GET requests) to retrieve status updates.
Registering a Postback URL
There are two ways to register postback URLs:
Web Portal – Static URL
Register your postback URLs via our web portal, as described in this guide. When registering a postback URL in the portal, we verify the availability and setup by sending a completely empty postback. This postback must be received with an HTTP 2xx response to successfully register the URL.
Registering your URL via the portal allows you to use additional security options such as an authorization header and checksum validation.
POST Request – Variable URLs
You can also dynamically specify a postback URL for specific transactions by including it in the POST request.
This functionality is meant to separate postbacks into different “buckets” that make sense for your implementation, for example to differentiate between environments (staging, production, etc.). This functionality is not intended to separate postbacks per transaction, as this circumvents the postback queuing system.
Dynamic postback URLs do not support additional security features such as authorization headers or checksum validation.
How to implement our postbacks correctly?
To prevent postbacks from being queued, we recommend the following steps as soon as you receive a postback:
Perform a security validation:
Check the authorization header (if applicable).
The body must be valid JSON, otherwise skip to step 2.
If applicable, perform checksum validation:
The JSON must contain a
checksumfield, otherwise skip to step 2.The checksum value must be correct, otherwise skip to step 2.
Always return an HTTP 2xx status code, even if validation fails. In case of failed validation, skip the rest of the processing. This prevents postback queues from forming.
If validation succeeds, process and store the verified postback.
Execute your further business logic.
⚠️ Always return a 2xx response
Your postback endpoint must always return an HTTP 2xx status code, even if validation fails or errors occur. If you don’t, Signhost will queue all subsequent postbacks, which can cause significant delays in receiving transaction updates.
What happens if the postback URL is unavailable or does not accept requests?
If your postback URL does not respond with a 2xx HTTP status, we will retry sending the postback with increasing intervals. All subsequent postbacks will be placed in a queue and wait until the first postback in the queue is successfully completed with a 2xx status.
New postbacks are only retried after the first in the queue succeeds. After the first postback is completed, deferred requests are processed one by one. If the first postback in the queue cannot be delivered within 48–72 hours, the entire queue will be cleared.
How to prevent data loss?
Because postbacks can fail, it is crucial to always accept and store incoming data immediately with an HTTP 2xx response. This prevents data loss and allows you to process everything later.
Further reading
More technical details about the postback service can be found in our complete API documentation.