Scrivito allows you to specify URLs you want to be requested each time a working copy of your CMS gets published. Such webhooks let you call web services in order to trigger actions related to the availability of new content such as prerendering your website, sending email notifications, posting messages to collaboration tools like Slack, etc.
You can provide up to ten URLs per CMS. Scrivito will contact each of them immediately after a publish occurred.
You can define your webhook URLs on the settings page of the corresponding website in your Dashboard.
The URLs need to start with https://.
For each URL, a secret can be specified. If you do, the webhook call will include a JWT (JSON web token) – see Securing webhooks below.
All webhook calls are logged. You can view the log directly on the settings page of your website.
Every webhook is called with a POST request containing the following data:
base_revision_id – the ID of the published revision’s base revision.event_id – a hexadecimal string identifying a particular publish.event_time – the time stamp of the publish.event_type – always publish.published_obj_ids – the list of the IDs of the CMS objects that have been modified in the working copy before publishing it.revision_id – the ID of the revision that has been published.tenant_id – the ID of the CMS concerned.user_id – the ID of the user who performed the publishing action (may be null).workspace_id – the ID of the working copy that has been published.workspace_title – the title of the working copy that has been published.Note that further properties may be added to the payload in the future, so your application should not reject requests because of excess properties in the payload.
A call to a webhook fails if a connection cannot be established within five seconds or the response takes longer than ten seconds. In these cases, Scrivito retries up to nine times with an exponential backoff (1 minute, 2 minutes, 4 minutes, and so on).
For security reasons, you might want your web services to only accept requests originating from Scrivito. In order to achieve this, you can set up a secret token for each publish webhook in the Dashboard (see above).
If a secret token has been specified for a webhook, Scrivito sends a special HTTP header, Scrivito-Webhook-Signature, which contains a JWT allowing you to verify that the webhook request is authentic.
The JWT is signed using the secret token set in the Dashboard and applying the HS256 algorithm to it. To secure your web service, it should validate the JWT and make sure that the included SHA256 digest matches the request body.
The JWT includes the following fields:
exp – expiry time; used to prevent replay attacks.sha256 – SHA256 hexdigest of the request body; use it to verify the authenticity of the request.The JWT can be verified like shown the examples below.
Further fields may be added to the JWT in the future. Therefore, your code should not discard the JWT because of excess fields.
This implementation makes use of the jsonwebtoken package.
This implementation uses the jwt gem.