# Hook v1-beta

Do not build against this API

This is a beta endpoint that is subject to change. We recommend not to build integrations against this API. However, any hooks configured through this endpoint will continue to work and will be supported going forward, even if the API itself changes.

# Overview

The /hook endpoint allows hooks to be configured with conditional output topics. This enables dynamic routing based on the result of an action. A common use case is configuring Peppol as the primary delivery method, with an automatic fallback to email when Peppol delivery fails.

# Concept

A hook can define one or more output rules.
Each output rule consists of:
- when: a condition (e.g. HTTP status code)
- topic: the topic to publish when the condition matches
When multiple outputs are defined, the first matching when determines the resulting topic.
If no outputs are defined, the system falls back to the default topics.

# Conditional Output Behavior

The when field is evaluated against the result of the action.
Typical conditions are based on HTTP status codes such as 400, 404, or 500.

# Example: Peppol with Email Fallback

The following example configures Peppol as the primary action. If Peppol fails with specific error codes, the flow falls back to an email-related topic.

The Peppol hook:

{
  "id": "peppol",
  "action": "peppol",
  "name": "peppol hook",
  "topics": [
    "Send*"
  ],
  "output": [
    {
      "when": "400",
      "topic": "Send*Fallback"
    },
    {
      "when": "404",
      "topic": "Send*Fallback"
    },
    {
      "when": "500",
      "topic": "Send*Fallback"
    }
  ],
  "isActive": true
}

The mail hook peppol-fallback:

{
   "id": "peppol-fallback",
   "name": "mail",
   "action": "mailto:[ReceiverEmailAddress]?fallbackEmail={email-when-no-address-is-found}&version=1.0&includeAttachment=true",
   "topics": [
     "Send*Fallback",
     "Send*"
   ],
   "isActive": true
}

Optionally, by adding "Send*" to the mail hook, the hook is also registered for the multi-channel lookup(queryRecipientParty) with the channel name: "peppol-fallback".

It is also possible to register the mail hook specifically for SendInvoiceFallback to limit the fallback to invoices only. The mail hook can be configured with additional options, such as a separate templateId, to customize the mail flow for this scenario.

← User Review →