Using the Event Hub Subscription Service

Last updated 2 days ago

Using the Event Hub Subscription Service.

Table of Contents

Overview
Prerequisites
Notes
Create New Webhook Subscription
- Return Codes
- Replay of Content Events
Read Existing Webhook Subscriptions
Update Existing Webhook Subscriptions
Delete Existing Webhook Subscription
Table of Error Codes and Messages

Overview

The CoreMedia Event Hub Service is a cloud-only service, which enables you to subscribe to the events of CoreMedia Content Cloud. See Introduction to the Event Hub Service for how to activate the service for your instance. This how-to document shows you how you can administer webhook endpoints by yourself, using the event subscription service. The API of the subscription service is documented in https://documentation.coremedia.com/eventdeliveryconfig-api

Prerequisites

The URL of the webhook subscription service, which is provided by the CoreMedia support
The access token as the service is protected by JWT. The CoreMedia support showed you how to access the token. All calls to the subscription service must include the header Authorization Bearer <JWT token>
The 8-character tenant ID of your CMOC instance, which is also provided by the CoreMedia support.
The environment (live or preview) from which you want to consume the events.

Notes

Creating subscriptions with event filtering is described in a separate document. See Filtering Events with the Event Hub Service

Create New Webhook Subscription

You register a new webhook using the call

POST /<environment>.<tenant id>/config

The configuration of the webhook endpoint is sent as JSON body in the request, for example:

{
    "description": "Customer ACME, sandbox first",
    "namespace": "PUBLIC",
    "subscriptionTypes": [
        "CONTENT",
        "NOTIFICATION",
        "WORKFLOW"
    ],
    "enabled": true,
    "endpoint": {
        "endpointType": "WEBHOOK",
        "url": "https://acme.com/firstsandbox/eventHubHook",
        "method": "POST",
        "authenticationMethod": {
            "authenticationType": "BASIC_AUTH",
            "username": "evenhub-first-sandbox-user",
            "password": "passwordForEventHubHook"
        },
        "headerParameters": {
            "Authorization": "Bearer 5bbryflnm897q38j6a9ug9p5rfehf5mcbn7"
        }
    }
}

Provide a description for the configured webhook.
The namespace must be PUBLIC.
The subscriptionTypes are one or more from the three different event types the webhook can consume:
- CONTENT
- NOTIFICATION
- WORKFLOW
  
  For the live environment only the CONTENT event type is available.
enabled must be true to activate this webhook. Later you can set it to false to deactivate the webhook without deleting the webhook.

The endpoint configures the actual communication from the event hub service to the webhook:

endpointType must be WEBHOOK. Other endpoint types are reserved for internal use by CoreMedia and are not available for customers.
url is the URL of the webhook endpoint. Only https URLs are allowed.
The request method must be POST or PUT.
authenticationMethod configures the authentication method used by the event hub service when sending the events to the webhook URL. Currently, only basic authentication is supported. To that end, set authenticationType to BASIC_AUTH and username and password. Contact CoreMedia for other authentication schemes.
Alternatively you can use a bearer authentication setting a header in headerParameters, which are the list of header parameters which are sent to the webhook URL along with the events. The example below shows an example of Authorization header parameter.

{
    "description": "Customer ACME, sandbox first",
    "namespace": "PUBLIC",
    "subscriptionTypes": [
        "CONTENT",
        "NOTIFICATION",
        "WORKFLOW"
    ],
    "enabled": true,
    "endpoint": {
        "endpointType": "WEBHOOK",
        "url": "https://acme.com/firstsandbox/eventHubHook",
        "method": "POST",
        "headerParameters": {
            "Authorization": "Bearer 5bbryflnm897q38j6a9ug9p5rfehf5mcbn7"
        }
    }
}

If successful, the response body looks like this:

{
    "id": "a324392a-8b69-4e1e-a72b-22a02d1291f8",
    "tenantId": "<tenant id>",
    "sourceId": "preview",
    "description": "Customer ACME, sandbox first",
    "namespace": "PUBLIC",
    "subscriptionTypes": [
        "CONTENT",
        "NOTIFICATION",
        "WORKFLOW"
    ],
    "enabled": true,
    "endpoint": {
        "endpointType": "WEBHOOK",
        "url": "https://acme.com/firstsandbox/eventHubHook",
        "method": "POST",
        "authenticationMethod": {
            "authenticationType": "BASIC_AUTH",
            "username": "xxxxxxxx",
            "password": "xxxxxxxx"
        }
    }
}

Sensitive data like password, user and headers are hidden in the response.

You can configure multiple subscriptions for the same event type, but there are some restrictions as shown below.

Return Codes

A successful creation of the webhook subscription returns 201 (Created). You will get 400 (Bad request) if the configuration is invalid, for example, an invalid webhook URL. In some cases, the subscription service will decline the subscription and return 409 (Conflict):

Duplicate endpoint: You are trying to subscribe the same webhook endpoint which has been already subscribed to the same event type.
Maximum number of subscriptions: For a given pair of environment and tenant there is a limit of subscriptions, which is currently 10.
Maximum number of subscriptions for an event type: For a given triple of environment, tenant and event type there is a limit of subscriptions, which is currently 4.

In case of an unsuccessful request, the response body contains JSON with an error message. For example,

{
    "statusCode": 400,
    "messages": [
        "endpoint.url: must be a valid URL"
    ]
}

See Table of Error Codes and Messages for the comprehensive list of all error codes and messages.

Replay of Content Events

When you create a new subscription for the CONTENT event type, only the content events since the registration are sent to the webhook. However, you can request a replay of all content items by adding the query parameter replay=true to the POST URL:

POST /<environment>.<tenant id>/config?replay=true

The received event stream will start with synthetic creation events for all content items in the respective repository before switching to the live event stream. The replay option is only available for content events as there are no replayable events for the other event types.

Read Existing Webhook Subscriptions

You get all registered webhook subscriptions for a given environment and tenant using the request

GET /<environment>.<tenant id>/config

The response body looks like below

{
    "items": [
        {
            "id": "a324392a-8b69-4e1e-a72b-22a02d1291f8",
            "tenantId": "<tenant id>",
            "sourceId": "preview",
            "description": "Customer ACME, sandbox first",
            "namespace": "PUBLIC",
            "subscriptionTypes": [
                "CONTENT"
            ],
            "enabled": true,
            "endpoint": {
                "endpointType": "WEBHOOK",
                "url": "https://acme.com/firstsandbox/eventHubHookForContentEvents",
                "method": "POST",
                "authenticationMethod": {
                    "authenticationType": "BASIC_AUTH",
                    "username": "xxxxxxxx",
                    "password": "xxxxxxxx"
                }
            }
        },
       {
            "id": "36e7d0cd-b8d4-42f8-89e8-e1af4b990e70",
            "tenantId": "<tenant id>",
            "sourceId": "preview",
            "description": "Customer ACME, sandbox first",
            "namespace": "PUBLIC",
            "subscriptionTypes": [
                "NOTIFICATION",
                "WORKFLOW"
            ],
            "enabled": true,
            "endpoint": {
                "endpointType": "WEBHOOK",
                "url": "https://acme.com/firstsandbox/eventHubHookForNotificatonAndWorkflows",
                "method": "POST",
                "headerParameters": {
                    "Authorization": "xxxxxxxx"
                }
            }
        }

    ]
}

Update Existing Webhook Subscriptions

The example above shows two subscriptions for the tenant and environment preview, one with the ID a324392a-8b69-4e1e-a72b-22a02d1291f8 and one with 36e7d0cd-b8d4-42f8-89e8-e1af4b990e70. You can change the subscription using the following call:

PUT /<environment>.<tenant id>/config/<subscription id>

As for the creation of a new webhook subscription, send the changed configuration as a JSON body. For example, to disable the subscription with the ID a324392a-8b69-4e1e-a72b-22a02d1291f8 send the call

PUT /preview.<tenant id>/config/a324392a-8b69-4e1e-a72b-22a02d1291f8

with the JSON body

{
    "description": "Customer ACME, sandbox first",
    "namespace": "PUBLIC",
    "subscriptionTypes": [
        "CONTENT"
    ],
    "enabled": false,
    "endpoint": {
        "endpointType": "WEBHOOK",
        "url": "https://acme.com/firstsandbox/eventHubHookForContentEvents",
        "method": "POST",
        "authenticationMethod": {
            "authenticationType": "BASIC_AUTH",
            "username": "evenhub-first-sandbox-user",
            "password": "passwordForEventHubHook"
        }
    }
}

Delete Existing Webhook Subscription

Delete an existing webhook subscription using the call

DELETE /<environment>.<tenant id>/config/<subscription id>

For example, to delete the subscription with the ID a324392a-8b69-4e1e-a72b-22a02d1291f8 send the call

DELETE /preview.<tenant id>/config/a324392a-8b69-4e1e-a72b-22a02d1291f8

Table of Error Codes and Messages

Return Code

Message

Description

400 (Bad Request)

Missing input

The required JSON body is missing.

Invalid ID

The ID given for GET/PUT/DELETE requests on individual subscriptions is not a valid UUID.

Input cannot be deserialized

The given request body is no valid JSON according to the spec. This can be generally malformed input or,for example, misspelled enum values.

Namespace '<name>' is forbidden

The calling user doesn’t have sufficient rights to use the requested subscription namespace.

Namespace 'PUBLIC' does not allow endpoint type '<endpoint_type>'

Only webhook endpoints are allowed for the PUBLIC namespace.

Namespace 'PUBLIC' does not allow subscription of '<event_type>' events

The PUBLIC namespace only allows the subscription to CONTENT, NOTIFICATION and WORKFLOW events.

Use of service name is reserved

A subscription with 'PUBLIC' namespace must not define a service name.

Service name is required

Only relevant for internal subscriptions. An internal subscription must have a service name.

Namespace is immutable

The namespace assigned when creating a subscription cannot be changed when updating the subscription.

A property within the submitted JSON has a validation error, for example a null value where a value is required.

409 (Conflict)

Duplicate endpoint '<endpoint_url>'

A specific endpoint can only be used once per event type.

Maximum number of 10 subscriptions reached

The total number of subscriptions is limited to 10.

Maximum number of 4 subscriptions for stream '<stream_type>' reached

The total number of subscriptions per event type is limited to 4.

Is this page useful?