Status updates and hooks (callbacks)
To receive and process real-time updates and status information of your sent documents, you can use a mechanism of "hooks" in addition to regular API calls.
Here's how hooks work:
Real-time Status Information: Our hooks automatically respond to changes in the status of your documents. This allows you to receive real-time updates on the progress of your shipments.
Customizable Actions: You can use the hooks to customize shipment statuses in your system as well, or do specific actions on specific shipment statuses.
No need to poll: Hooks ensure that you don't have to poll the status of a shipment every time, reducing the number of API calls that need to be made.
Hooks can be managed through the /api/callback configurations.
A callback will always be an HTTP POST on your configured endpoint.
The body of such a callback will look like this:
{
"EventName" = " DocumentStatusUpdated",
"OccuredAtUtc" = "DateTime.UtcNow",
"Properties" = [
{
"Key" = "NewStatus",
"Value" = "StatusEnumValue"
},
{
"Key" = "DocumentReference",
"Value" = "documentReference"
},
{
"Key" = "ExternalId",
"Value" = "documentExternalId"
}
]
}
EventName: This will always be "DocumentStatusUpdated".
DocumentReference: The reference of the document as provided by you when uploading the document. When uploading, this field is optional. If you did not provide it when uploading, this Property will not be provided.
ExternalId: The unique ID of a document in Postbird. This ID is returned when uploading the document.
StatusEnumValue: Contains the new status of the document. Possible values are:
UploadAwaiting = 0, // The document has been uploaded into our system and is waiting to be processed
UploadError = 1, // Something went wrong while uploading in our system
UploadOk = 2, // The document has been properly uploaded and is ready for further processing
PdfCriticalValidationAwaiting = 3, // Postbird has started validating the PDF document
PdfCriticalValidationError = 4, // The document is not a valid PDF or the paper size is invalid (not A4)
PdfCriticalValidationOk = 5, // Postbird has successfully completed validation of the PDF document
AddressAwaiting = 6, // Postbird starts the validation of the address
AddressError = 7, // The address has no valid structure or was not found
AddressOk = 8, // The address is correct
PaymentAwaiting = 9, // Postbird has started the payment of the document
PaymentError = 10, // Something went wrong with the payment of the document (insufficient balance)
PaymentOk = 11, // The document has been paid
SentToNotificationService = 12, // The document was sent to the print center
SentToNotificationServiceError = 13, // Something went wrong sending the document to the print center
AwaitingPrint = 14, // The document is waiting in the print center for printing
Printed = 15, // The document has been printed
Send = 16, // The document was delivered to the postal operator
NotDelivered = 17, // The document was not delivered to the recipient (wrong address, moved, ...)
NormalSendingFailed = 18, // The postal operator could not deliver the document
Delivered = 19, // The registered document has been delivered
Canceled = 99 // The document was canceled by a Postbird employee (at the request of the customer)
Read more: Enums