When an event for which you have registered a webhook happens, Sproom will send a request to the registered webhook url


All Requests will contain the following fields

Common webhook payload fields
Field nameDescription
webhookType Type of webhook event, one of:
  • documentStatusChanged - A document changed status
  • documentReceived - A new document was received
  • test - A webhook test was triggered by the /api/webhooks/{webhookId}/test
companyId Id of the company that "owns" the document that this webhook event happened for
documentId Id of the document that this webhook event happened for

In addition webhooks will have additional information, dependent on the webhook type:

documentReceived webhook payload fields
Field nameDescription
documentType Type of document received, one of:
  • ApplicationResponse
  • Catalogue
  • CatalogueDeletion
  • CatalogueItemSpecificationUpdate
  • CataloguePricingUpdate
  • CatalogueRequest
  • CreditNote
  • Invoice
  • Order
  • OrderCancellation
  • OrderChange
  • OrderResponse
  • OrderResponseSimple
  • Reminder
  • Statement
  • UtilityStatement
  • DespatchAdvice

true/false - indicates whether this document has related documents.

The value is true for Invoice and CreditNote that have a UTS reference, and for UtilityStatements with a reference to an Invoice or a CreditNote To see documents that are referring each other, use the GET api/documents/{documentId}/references endpoint.

Example payload for documentReceived webhook call:

{ "webhookType": "documentReceived", "companyId": "ced1f14e-9002-4ffc-b647-7c1f10e4385a", "documentId": "6d25b2c1-a7cf-4d10-a835-ad19863f67ff", "documentType": "applicationResponse", "hasRelatedDocuments": false }

documentStatusChanged webhook payload fields
Field nameDescription
documentStatus New status for the document, one of:
  • created
  • endpointNotFound
  • endpointAdded
  • sendLimitExceeded
  • sendLimitIncreased
  • incompletePackage
  • timeout
  • receiveLimitExceeded
  • receiveLimitIncreased
  • returnedToSchematronEnrichment
  • schematronEnrichmentIsDone
  • incomplete
  • incompleteReturned
  • transmissionStarted
  • sent
  • received
  • transmissionCompleted
  • pendingApproval
  • approved
  • rejected
  • error
  • errorMax
  • errorMin
  • oioSchemaValidationError
  • schematronValidationError
  • duplicateFileError
  • sendNemHandelError
  • runtimeError
  • sendItellaError
  • sendSproomError
  • errorProcessingAttachments
  • customValidationError
  • canceled
  • deleted
  • testModeError
  • senderMismatchError
  • sendEvenexError
  • sendPageroError
  • sendBaswareError
  • sendInExChangeError
  • sendLetterError
  • sendStatOilError
  • deliveryRestrictionError
  • sendIbisticError
  • sendError
  • sendEbuilderError
  • applicationReponseProfileReject
  • applicationReponseTechnicalReject
  • customerNotSubscribedToBilsim
  • customerNotSubscribedToUts
  • applicationReponseBusinessReject
  • internal
statusDetails Detailed information about the new status. See below

Example payload for documentStatusChanged webhook call:

{ "webhookType": "documentStatusChanged", "companyId": "e042e119-fd0c-4dd6-bf7e-02564c9fbd7b", "documentId": "18b1ee00-b6ed-43f4-8c8f-960a014b580c", "documentStatus": "created", "statusDetails": { "dateTime": "2021-02-01T09:15:17.071Z", "state": "incomplete", "statusCode": 221, "deliveryType": "sproom", "message": null, "failedProperties": [ { "name": "customerReference", "attemptedValue": "Økonomi", "validationRules": [ { "type": "regex", "errorMessages": [ { "language": "da", "message": "Kundereferencen SKAL bestå af to bogstaver efterfulgt af et eller flere tal" } ], "validationParameters": { "pattern": "^[A-Za-z]{2}[0-9].+$" } } ] } ] } }

Signature verification

Every webhook callback will be signed, and the signature will be in an X-Signature http header. It's important to verify signature for the webhook calls, to be sure that it is in fact Sproom that makes the call, and not a "man in the middle" or similar "attacker"

See the api/webhooks/key endpoint to get the public key needed for verification, and a simple example of how to verify the signature. A complete example for signature verification can also be found here: https://gist.github.com/gaevoy/ddf0478d17976cd4e492b0518dce69cd

Webhook response

The webhook call is expected to return a success HTTP status code (200 - 299) in a reasonable amount of time.

Webhook responses
HTTP status code in the success range, 200 - 299Webhook call was successful. Sproom will not call again
HTTP status code outside of the success rangeWebhook call not successful. Sproom will periodically retry the call
Takes more than 100 seconds to respondWebhook call timed out. Sproom will retry the call.


If a webhook call doesn't succeed, Sproom will retry it periodically for 24 hours.

This means that webhook url's should never be down for longer periods of time. If you need to take your webhook service offline, you should delete or change the webhook registration in Sproom.