{
"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"
}
}
}
Using the Event Hub Subscription Service
Using the Event Hub Subscription Service.
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
orpreview
) 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:
-
Provide a
description
for the configured webhook. -
The
namespace
must bePUBLIC
. -
The
subscriptionTypes
are one or more from the three different event types the webhook can consume:-
CONTENT
-
NOTIFICATION
-
WORKFLOW
For the
live
environment only theCONTENT
event type is available.
-
-
enabled
must betrue
to activate this webhook. Later you can set it tofalse
to deactivate the webhook without deleting the webhook.
The endpoint
configures the actual communication from the event hub service to the webhook:
-
endpointType
must beWEBHOOK
. Other endpoint types are reserved for internal use by CoreMedia and are not available for customers. -
url
is the URL of the webhook endpoint. Onlyhttps
URLs are allowed. -
The request
method
must bePOST
orPUT
. -
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, setauthenticationType
toBASIC_AUTH
andusername
andpassword
. 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 ofAuthorization
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. |
|
<property path> <message> |
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. |