EventHook API and schemas

[mortenoh]

Event Hooks DHIS2-12194

Event hooks represent a way to have external system react to what's happening inside of DHIS2. We are currently at a very early stage but it does now work for metadata paths which is the focus for our 2.40 release. All payloads/schemas download should be considered experimental and be changed before release.

EventHook schema

Property	Description
id	Unique Identifier (auto-generated if not present)
name	Name of event hook
enabled	Is the event hook enabled or not (default: true)
source.path	Start of path of events to listen on, follow <main-type>.<sub-type>.<id> for example metadata.organisationUnit.bRNvL6NMQXb
source.fields	Field filtering to be applied to affected objects (or objects if a collection is sent)
targets	One one more targets that is fired after valid path is confirmed.

webhook Target

Hook that does at POST with json payload to an external service.

Property	Description
type	webhook
url	Target service (a POST wil be made here with the event payload)
headers	An object of additional headers to apply
auth	Apply Authorization header with supplied auth type (see below for api-token and http-basic examples

console Target

Simple console logger using log.info(event) with the json payload.

Property	Description
type	console

EventHook payload examples

EventHookwith * field filter listening on metadata.* changes. Target is webhook with api-token auth type.

{
    "id": "bRNvL6NMQXb",
    "name": "hook1",
    "enabled": true,
    "source": {
        "path": "metadata",
        "fields": "*"
    },
    "targets": [
        {
            "type": "webhook",
            "url": "http://localhost:8081/api/gateway",
            "auth": {
                "type": "api-token",
                "token": "EB3F6799-AA5A-47E8-B6B7-97EA54EB3873"
            }
        }
    ]
}

EventHookwith * field filter listening on metadata.* changes. Target is webhook with http-basic auth type.

{
    "id": "bRNvL6NMQXb",
    "name": "hook1",
    "enabled": true,
    "source": {
        "path": "metadata",
        "fields": "*"
    },
    "targets": [
        {
            "type": "webhook",
            "url": "http://localhost:8081/api/gateway",
            "auth": {
                "type": "http-basic",
                "username": "admin",
                "password": "admin"
            }
        }
    ]
}

Event schema

This represent the current Event schema that is sent out for every published event. Focus and examples are on metadata (but the general idea should apply everywhere)

Given a event hook that listens on metadata and has the fields id,name applied a an example event payload currently looks like this.

{
    "path": "metadata.organisationUnit.tXjhduKKhY5",
    "createdAt": "2022-12-21T12:22:46.606308+07:00",
    "meta": {
        "op": "create"
    },
    "object": {
        "name": "Country",
        "id": "tXjhduKKhY5"
    }
}

Property	Description
path	Full path of event, including id if applicable to type
createdAt	ISO8601 date of when the event occured
meta	Object block which currently has no schema (internally represented by a Map<>). For metadata its currently used to tell what type of operation occured create update delete but what exactly else should be there, or if there is a better way of doing this is up to debate
object	The attached object (could be empty in some cases where a system event has occured). In this case there was an creation of a new OrganisationUnit so this is that object with field filtering applied (in the same way you would get this if you did /api/organisationUnits/ID?fields=id,name)

[cjmamo]

How would this work for SMS events? For example, I want to fire a webhook call when a message is POSTed to /api/sms/inbound. What happens if the webhook call cannot be completed for any reason?

[mortenoh]

That is still being debated @claudemamo, right now it will be logged as a failed webhook attempt (similar to how our internal T2A is doing it). If we want to have more sophisticated retry-logic, or not I'm not sure yet. There will also be JMS and Kafka target which should be more stable (and then you can listen to them directly). We will have a open discussion regarding this in January 2023.

[mortenoh]

Also, the main focus is for metadata and a few internal system events initially (it's easy enough to add more places though, so let's see)

[cjmamo]

I'm wondering how it can be extended to SMS. Would the source path be sms.inbound? One suggestion I'd make is to rename targets to actions. It makes more sense to me to fire an action rather than fire a target.