Webhook triggers let you specify under which circumstances an HTTP call will be performed towards your endpoint:
You can add as many triggers as you want to a single webhook. DatoCMS supports events for these kind of objects:
Record: triggers whenever a record is created, updated, deleted, published, unpublished or all of the above. Additionally, you can trigger the webhook only for specific records or records belonging to specific models
Model: triggers whenever a model is created, updated, deleted or all of the above. Changes made to a model's field will trigger a call as well. Additionally, you can trigger the webhook only for specific models
Upload: triggers whenever any upload is created, updated, deleted or all of the above
Build trigger: triggers whenever an build gets triggered
Environment: triggers whenever an environment gets created, updated promoted or deleted
If you want, you can also customize the HTTP body of the outgoing requests. To do that hit the Send a custom payload? switch and provide the new payload.
You can use the Mustache language to make the payload dynamic. The original payload we would send is used as source for the template. You can experiment with the Mustache language in their sandbox, or read their docs.
As an example, this custom payload template:
{"message": "{{event_type}} event triggered on {{entity_type}}!","entity_id": "{{#entity}}{{id}}{{/entity}}"}
Will be converted into the following HTTP body:
{"message": "update event triggered on item!","entity_id": "123213"}
You are not limited to send JSON payloads: just make sure that if the payload is not in JSON format you configure the proper Content-Type
header.
In a similar way, you can also insert Mustache tags in the webhook URL.
DatoCMS will perform an HTTP POST request towards the specified endpoint. The HTTP body will be in JSON format, and will contain all the information relevant to the event just happened.
As an example, in the case of an event of record update, you can access the record state both before the update operation (previous_entity
) and after (entity
) , making it easier to make a diff and see exactly what fields in the record changed:
{"environment": "foo-bar","entity_type": "item","event_type": "update","entity": {"id": "39830648","type": "item","attributes": {"name": "Mark Smith",},"relationships": {"item_type": {"data": {"id": "810928","type": "item_type"}},"creator": {"data": {"id": "42011","type": "account"}}},"meta": {"created_at": "2018-10-28T18:44:32.776+01:00","updated_at": "2021-08-17T09:11:56.145+02:00","published_at": "2021-08-17T09:11:56.143+02:00","publication_scheduled_at": null,"unpublishing_scheduled_at": null,"first_published_at": "2018-10-28T18:44:32.789+01:00","is_valid": true,"status": "published","current_version": "117626080","stage": null}},"previous_entity": {"id": "39830648","type": "item","attributes": {"name": "John Smith",},"relationships": {"item_type": {"data": {"id": "810928","type": "item_type"}},"creator": {"data": {"id": "42011","type": "account"}}},"meta": {"created_at": "2018-10-28T18:44:32.776+01:00","updated_at": "2021-08-17T09:11:53.371+02:00","published_at": "2021-08-17T09:11:53.367+02:00","publication_scheduled_at": null,"unpublishing_scheduled_at": null,"first_published_at": "2018-10-28T18:44:32.789+01:00","is_valid": true,"status": "published","current_version": "117626079","stage": null}}}
The webhooks calls have some custom headers:
x-site-id
with the site id
x-webhook-id
with the webhook id
x-environment
with the environment id, if the entity that generates the webhook lives in an environment, for example a record
Each time a webhook gets triggered, DatoCMS creates a WebhookCall
object that contains all the relevant information about what just happened. You can browse webhook calls under the Webhooks activity log section of your administrative area, or using our API.
In case something went wrong (4xx/5xx HTTP status code, server timeout, etc.) you will be able to manually resend the webhook:
DatoCMS expects that integrations respond within 5 seconds of receiving the webhook payload. If your service takes longer than that to complete, then DatoCMS terminates the connection and the payload is lost.
Since it's impossible to predict how fast your service will complete, you should do all of "the real work" in a background job. Resque (for Ruby), RQ (for Python), or RabbitMQ (for Java) are examples of libraries that can handle queuing and processing of background jobs.
Note that even with a background job running, DatoCMS still expects your server to respond within five seconds. Your server needs to acknowledge that it received the payload by sending some sort of response. It's critical that your service performs any validations on a payload as soon as possible, so that you can accurately report whether your server will continue with the request or not.