Creating a webhook subscription is a two-step process. You'll first need to set up how you want your webhook to behave and what events should it listen to. After that, you'll set up your server to receive and manage the payload.
Subscribe via the Partner Portal
To set up a webhook, go to the Webhooks page of your Partner Portal. You will only see this page if you have the appropriate permissions (ask your administrator).
From there, click the New button.
Configure the necessary fields as described below. When you're finished, click Add webhook.
Subscribe via the API
NOTE: You cannot use the Partner Portal to edit subscriptions created or updated using the API. Since the webhook interface in the Terminal only supports a subset of the API, you must choose either the Terminal or this API for managing webhook subscriptions.
For instance, the API allows you to manage subscriptions down to the
subject:action level while Partner Portal only allows you to filter down to
Webhook subscriptions require a few configuration options before you can make use of them. As a general rule, for a subscription to receive events it must have the following minimum configuration:
- A valid, accessible endpoint URL
- One or more valid event types (or a wildcard)
The endpoint URL of the server that will receive the webhook
This endpoint should be secured via HTTPS to ensure end-to-end encryption.
Setting a webhook secret allows you to ensure that
POST requests sent to the
endpoint URL are signed by Bold Penguin. When you set a secret, you'll receive
X-Signature header in the webhook POST request. See securing
webhooks for more information and working with payload
If your server requires the request to contain a static header for
authentication or other purposes, you can configure that here. headers must
follow the format
Events are at the core of webhook subscriptions. Webhooks fire whenever a subscribed event occurs, which your server's endpoint URL receives and acts upon.
You can subscribe to one or more subjects or the wildcard event. Using the API, you can also subscribe to individual actions for a subject.
A full list of webhook events, and when they execute, can be found on the event payloads page.
By default, webhook deliveries are inactive. You can enable the delivery of webhook payloads by setting Active to true/checked.