Skip to main content

Subscriptions

You only need this resource for receiving webhooks, not for sending them!

A Subscription listens to webhook messages and delivers them to the Subscription's destination.

When a Subscription is created, a Binding ID must be specified. The Subscription will be bound to it and will listen to webhook messages published to that Binding.

Listening to topics

A Subscription only listens to the topics specified in the Subscription's topics attribute. If that attribute is set to all available topics that an Binding offers, then it will effectively listen to all published webhook messages of an Binding. If the topics attribute is an empty array, the Subscription will not listen to any webhook messages, meaning that it will also not deliver any webhooks.

Webhook delivery

Webhook messages are delivered via HTTPS POST requests to the destination_url attribute of the Subscription.

Each published webhook message generates one POST request. An exception to this rule is when the server at destination_url fails to properly receive the request, in which case the webhook message could then be re-delivered multiple times until a delivery succeeds. See the Retrying page for more information.

API

Endpoints
GET
/v1/subscriptions
GET
/v1/subscriptions/:id
POST
/v1/subscriptions
PUT
/v1/subscriptions/:id
Resource attributes
name*
string
The resource unique name
binding*
name|id
The Binding to be used as the source of webhooks
key*
name|id
The Key used to sign webhooks
topics*
array[name|id]
A list of Topics this subscription will respond to
destination_url*
URL
The URL where webhooks will be delivered to