Creating Webhooks
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
Alternatively, you can choose to create and update your webhooks through the Webhooks 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
the event
.
Configuration
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)
Active
set totrue
Endpoint URL
The endpoint URL of the server that will receive the webhook POST
requests.
This endpoint should be secured via HTTPS to ensure end-to-end encryption.
Secret
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
the X-Signature
header in the webhook POST request. See securing
webhooks for more information and working with payload
signatures.
Header
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 Name: Value
.
Events
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.
Active
By default, webhook deliveries are inactive. You can enable the delivery of webhook payloads by setting Active to true/checked.