Webhooks are a feature that allow third party applications to listen for event notifications regarding story and collection workflows from Bold CMS. You can find the webhooks dashboard under Settings -> Webhooks.
Payload
When creating a webhook, you specify the URL you would like to be notified on, and the events for which you wish to be notified. A URL must be of maximum 255 characters. If any of the events to which a webhook subscribed occur, a POST request with the following payload body will be sent to the webhook URL:
{ "v1": { "event": { event fields as described below }, "data": { various story or collection data fields } }}
| Event Field | Description |
| id | This will be a number that uniquely identifies this event trigger |
| name | Name of the triggering event as selected in dashboard e.g. story-approve |
| time | UNIX timestamp in milliseconds at which the event triggered |
Signature
You may additionally specify a secret when creating or editing a webhook. This secret will be used to sign the webhook payload using HMAC SHA-256 and the resulting 64 character hex digest will be sent in the POST request header as X-Qt-Signature. If no secret is specified this header field will appear blank.
You can verify the authenticity of the received message by using the same algorithm and the secret to generate a hex digest from the webhook body. It should match the one received in the signature header.
Retries
Upon firing a POST request, if the endpoint specified returns an HTTP response code of 300 or greater, it will be considered an error. The connection and socket timeouts for this request are both 3 seconds. The webhook will retry 3 more times, each at an interval of 10 seconds, until a successful response is elicited or the maximum retry limit is reached.
Sample Request
Headers
POST /story-submit HTTP/1.1
Host: ping.requestcatcher.com
Connection: close
Accept-Encoding: gzip, deflate
Content-Length: 4808
Content-Type: application/json
User-Agent: Apache-HttpClient/4.5.10 (Java/1.8.0_275)
X-Qt-Signature: 8f1b736a3c8e7f7e4c45c7e07f80616a080e1d25f8e3184e5d62d153fef5831a
Body
{"v1": {"event": {"id": 1024,"name": "story-submit","time": 1619007030964},"data": { data fields}}}
Logs
You can view logs for a particular webhook by clicking on 'View Logs' on an entry in the webhooks table. Logs are automatically deleted after 30 days.
Bold Release Note - 8 Jun 2021
Webhooks for various story state events in Bold
Integrate Bold with any third party system with the help of Webhooks.
Go to Settings > Webhooks > Add Webhook to setup the URL.
Multiple story and collection workflow events are now available for webhook calls to be listened to.
Bold Release Note - 21 Sep 2021
Note on Webhooks
Webhook payloads now include the parent section of the section that the story is directly linked to and also contains the associated section-collection information.