Webhooks

Integrating webhooks

Introduction

Webhooks allows your app to receive notifications whenever there are updates to a chosen set of events. For example, you could set up a webhook for the content_item.created event and subscribe to be notified whenever a new Content item is created.

Webhooks update notifications are sent as POST requests to a URL that you supply. Notifications include the newly updated value, as well as the base resource.

Webhooks are often used for:

  • Deploying a static website when content is changed.
  • Syncing data to a external search engine platform.
  • Update legacy databases.
  • Triggering (Notify) notifications in apps.

Event types

There are 11 events that can trigger a Webhook notification.

Type
content_item.published
content_item.unpublished
content_item.created
content_item.changed
content_item.deleted
asset.created
asset.changed
asset.deleted
container.created (Story)
container.changed (Story)
container.deleted (Story)

Managing webhooks

A list containing all notifications send to your webhook van be found on the Webhook detail page in your Prepr account. Attempts can be viewed and retried. You can also view the response the Prepr server received from your endpoint.

Managing webhooks in Prepr

Setting up an endpoint

Follow the guidelines below to successfully create a webhook endpoint.

Setting up the endpoint

You need to set up your callback endpoint before you can set up a subscription. The endpoint must use HTTPS and be able to receive both GET and POST requests. All notifications will be sent as POST requests for now and include a JSON payload and Custom + Prepr headers to verify.

Configuring your webhook URL

Log-in to your Prepr account with a user that has owner, admin or developer rights.
Go to Settings -> Development -> Webhooks.

Create a new webhook by clicking 'Add webhook'. Enter the URL, the notifications will be sent to an optionally custom headers to protect you endpoint.

Select the events you want the webhook to be notified about and click 'Save'.

Response

Your endpoint should return a 2xx HTTPS response for all notifications. When other status codes are returned the notification is considered failed and will be retried.

If your webhook continues to fail for multiple times in 24 hours, your webhook will be disabled. The account owner will be notified in such event.

Performance Requirements

Respond to all webhook events in 12 seconds or less. After 12 seconds the notification is considered failed and will be retried.

Security guidelines

We recommend to protect the endpoints to which we will sent the notifications. This prevents unauthorized actions on your app.

When configuring your webhook in Prepr, add an Authorization header with a secret access token only your incoming webhook server knows.

Prepr will send all of the custom headers you added when sending a notification, including Authorization. If the values don't match, you can ignore the request.

Whitelisting Prepr Server IPs

You can ensure your app is always communicating with Prepr through one of our IP addresses.

87.233.165.0/26
2001:9a8:0:4b:: 64 bits

Webhook Signatures – advanced feature

Prepr will sign the webhook events it sends to your endpoints. We do so by including a signature in each event’s Prepr-Signature header. This allows you to validate that the events were sent by Prepr, not by a third party.

Before you can verify signatures, you need to store your endpoint’s id when creating a new Webhook. Each id is unique to the endpoint to which it corresponds. If you use multiple endpoints, you must obtain a id for each one.

Verifying signatures
The Prepr-Signature header contains the full json payload you receive.

Prepr generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing id as the key, and use the json payload string as the message.

Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Preventing replay attacks – advanced feature

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Prepr includes a timestamp in the Prepr-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

We recommend a tolerance of five minutes between the timestamp and the current time. We advise that you use Network Time Protocol (NTP) to ensure that your server’s clock is accurate and synchronizes with the time on Prepr's servers.

Prepr generates the timestamp and signature each time we send an event to your endpoint. If Prepr retries an event (e.g., your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the next delivery attempt.

Working with webhooks

Webhooks allows your app to easily receive notifications whenever there are updates to a chosen set of events. Webhooks update notifications are sent as POST requests to a URL that you supply.

For example, you could set up a webhook for the publication.created event and subscribe to be notified whenever a new content item is created.

Webhooks are often used for:

  • Deploying a static website when content is changed.
  • Syncing data to an external search engine platform.
  • Update legacy databases.
  • Triggering (Notify) notifications in apps.

Creating a webhook

Webhooks allows your app to easily receive notifications whenever there are updates to a chosen set of events. A typical example is when a content item is published, and the API is updated.

Create your webhook

To create a webhook, go to Settings > Developers > Webhooks and click 'Add webhook'. Fill in your endpoint URL. Please remember that webhook endpoints must start with https://.

Webhook triggers: events

There are different events that can trigger a webhook notification. You can choose content item, asset, or container events (such as created, changed, or deleted). For customer segmentation, there are person and segment events as well. Learn more about the event types on our developers portal.

Create a webhook

Webhook triggers: models

When you have selected a content item event, you will receive notifications when a content item is created, (un)published, changed, or deleted. You can further specify which content items you want to receive notifications from. Select one or more models to receive webhook events for content items of that specific model. Selecting none will act as a wildcard.

Create a webhook

Headers

There are some use-cases where an application requires some fields to be added in the header of the webhook payload. The most common headers are access tokens or a personal scope key. To add a custom header, enter a header key and value.

Create a webhook

Retry

Select the number of retries for an unfinished webhook. The default number is 35.

Managing existing webhooks

Webhooks allows your app to easily receive notifications whenever there are updates to a chosen set of events. A typical example is when a content item is published, and the API is updated.

Manage your webhooks

To get a quick insight into the webhook performances, go to Settings > Developers > Webhooks. The list view contains the webhooks in this Prepr environment (grouped by domain), and the selected webhook events. The error rate shows the number of failing webhooks in the last three days. Note:

Manage existing webhooks

Webhook attempts

To manage an existing webhook, go to Settings > Developers > Webhooks and click the specific webhook in the list. All attempts of this webhook of the last three days can be viewed and retried here. You can also view the response the Prepr server received from your endpoint.

Manage existing webhooks

Resending webhooks

You can resend a webhook event by clicking 'Resend' in the payload logging.

Error rates

In the case of a 100% error rate on the last day, the Prepr account owner will receive a notification email. If the webhook keeps failing for the next 24 hours the webhook will be disabled automatically.

Switch off webhook

You can easily switch off your webhook temporarily. Go to the detail page of your webhook via Settings > Developer > Webhooks, and disable the 'status' option.

Delete your webhook

When you no longer need the webhook, you can delete the webhook permanently. Click the 'Delete' button on the detail page, or delete the webhook from the list view.