Subscriptions¶

(For concrete examples, check out our bruno collection)

Subscriptions are the main mechanism for getting real-time events from the Bane NOR event backbone. The subscription is a reference to an application that wants events to be sent to a webhook endpoint. The subscriber can configure the authentication towards the endpoint in addition to an API key if that is needed.

Webhook endpoint¶

The endpoint can receive the event payload with additional metadata by using the CloudEvents HTTP binding.

Cloud events are sent by using the HTTP Protocol Binding. This means that the CloudEvents are part of the HTTP headers.

What does this look like¶

The CloudEvent is sent in binary content mode. This means that the contents of the payload will be cloudevent.data while the CloudEvent attributes are passed as HTTP headers. Here is an example message:

POST /event-endpoint HTTP/1.1
Host: example.com
Content-Type: application/json
Ce-Specversion: 1.0
Ce-Type: com.example.object.created
Ce-Source: /mycontext
Ce-Id: A234-1234-1234
Ce-Time: 2025-06-12T12:00:00Z
// Payload will be dependant on contents of the original message.
{
  "objectId": "abc-123",
  "status": "created"
}

Create Subscription¶

The following command can be used to create a subscription that uses an API key and basic authentication.

curl -H "Ocp-Apim-Subscription-Key: ApiKey" https://<bane-nor-api-endpoint>/event-issuer/v1alpha/{tenantId}/subscriptions \ 
-d '{"applicationId": "my-application", "event": "event-name", "URL": "https://my-endpoint.com/events}, \ 
"apiKey": { "header": "Ocp-Apim-Subscription-Key", "key": "API-key" }, \ 
"authentication": { "username": "user1", "password": "my-secure-password" }'

If only an API key is needed don't set the authentication and and only the apiKey section.