Add a new subscription

POST/subscriptions

Authorization

AuthorizationBearer token (JWT) · headerrequired

Request body

requiredapplication/json

New event to be distributed to subscribers.

typestringrequired

Allowed:PUBSUB

methodstringrequired

Allowed:PUSH

urlstringrequired

Publicly accessible URL that should receive the events

contactstringrequired

Email address to be contacted in case of problems with this subscription

topicstringrequired

ID of the topic to subscribe to

Responses

201Subscription created

typestringrequired

Allowed:PUBSUB

methodstringrequired

Allowed:PUSH

namestringrequired

ID of the subscription to be referenced in API calls

pathstringrequired

Path of subscription in project

topicobjectrequired

Show properties

idstringrequired

namestringrequired

pathstringrequired

ackDeadlineSecondsintegerrequired

min -9007199254740991 · max 9007199254740991

retryPolicystring | null

serviceAccountstringrequired

urlstringrequired

Publicly accessible URL that should receive the events

contactstringrequired

Email address to be contacted in case of problems with this subscription

institutionIdstringrequired

ID of the institution the current user belongs to

400Bad Request (invalid input)

messagestringrequired

errorsopenApiErrorItem[]required

min items 1

Show properties

Array of openApiErrorItem

openApiErrorItem

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

401Missing authentication

messagestringrequired

errorsopenApiErrorItem[]required

min items 1

Show properties

Array of openApiErrorItem

openApiErrorItem

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

403Invalid authorization

messagestringrequired

errorsopenApiErrorItem[]required

min items 1

Show properties

Array of openApiErrorItem

openApiErrorItem

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

404Topic for subscription not found

messagestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

413Payload Too Large (JSON body exceeds 400kb limit)

messagestringrequired

errorsopenApiErrorItem[]required

Show properties

Array of openApiErrorItem

openApiErrorItem

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

500Internal server error

messagestringrequired

tracestring | nullrequireddeprecated

Always null. Deprecated; may be removed in a future release.

Request

curl -X POST "/subscriptions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "PUBSUB",
  "method": "PUSH",
  "url": "https://example.com/my/webhook/for/this/subscription",
  "contact": "my-emergency-and-notifications-contact@ard.de",
  "topic": "topic-id-to-subscribe-to"
}'

const response = await fetch("/subscriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "type": "PUBSUB",
  "method": "PUSH",
  "url": "https://example.com/my/webhook/for/this/subscription",
  "contact": "my-emergency-and-notifications-contact@ard.de",
  "topic": "topic-id-to-subscribe-to"
})
});

Response

{
  "type": "PUBSUB",
  "method": "PUSH",
  "name": "de.ard.eventhub.subscription.subscription-id",
  "path": "projects/ard-eventhub/subscriptions/subscription-name",
  "topic": {
    "id": "urn:ard:permanent-livestream:topic-id",
    "name": "de.ard.eventhub.dev.urn%3Aard%3Apermanent-livestream%3Atopic-id",
    "path": "projects/ard-eventhub/topics/topic-name"
  },
  "ackDeadlineSeconds": 20,
  "retryPolicy": null,
  "serviceAccount": "name-of-service-account",
  "url": "https://example.com/my/webhook/for/this/subscription",
  "contact": "my-emergency-and-notifications-contact@ard.de",
  "institutionId": "urn:ard:institution:institution-id"
}