Webhooks

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

Payload

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
  • peppolParticipantVerificationChanged - A peppol participant verification status was changed
  • childCompanyEnrollmentChanged - There was a change in a company's enrollment status
companyId Id of the company that "owns" 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
hasRelatedDocuments

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.
documentId Id of the document that this webhook event happened for

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
documentId Id of the document that this webhook event happened for

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].+$" } } ] } ] } }

peppolParticipantVerificationChanged webhook payload fields
Field nameDescription
verificationStatus New status for Peppol Participant Verification, one of:
  • signed
  • revoked
verificationId The Guid of the verification

Example payload for peppolParticipantVerificationChanged webhook call:

{ "webhookType": "peppolParticipantVerificationChanged", "companyId": "e042e119-fd0c-4dd6-bf7e-02564c9fbd7b", "verificationId": "18b1ee00-b6ed-43f4-8c8f-960a014b580c", "verificationStatus": "signed" }

childCompanyEnrollmentChanged webhook payload fields
Field nameDescription
childCompanyName The name of the enrolled child company
childCompanyIdentifier The identifier of the enrolled child company. Contains:
  • schemeId
  • value
childCompanyId The unique identifier (Guid) of the enrolled child company
status The status of the company enrollment process. Can be one of:
  • accepted
  • rejected
  • expired
reason The reason for the enrollment rejection. It can be null.

Example payload for childCompanyEnrollmentChanged webhook call:

{ "webhookType": "childCompanyEnrollmentChanged", "companyId": "e042e119-fd0c-4dd6-bf7e-02564c9fbd7b", "childCompanyName": "ChildCompanyName", "childCompanyIdentifier": { "schemeId": "DK:CVR", "value": "12345678" }, "childCompanyId": "18b1ee00-b6ed-43f4-8c8f-960a014b580c", "status": "rejected", "reason": "invalid request" }

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
ResponseDescription
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.

Retries

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.