What are they?

Webhooks are events that are triggered whenever a change is published on your Prismic repository and the API is updated.  Up until now, you have had little control over what triggers your webhooks and we have been sending you webhooks for a wide range of events - potentially causing your website to rebuild even though you were just creating a new release in your Writing Room. With this new update you can monitor exactly what has changed, providing you a finer grain of control, the possibility of greater configuration,  and an improved interface.

How do they work and what can I do with them?

There are many things that you can do when your content changes. You may want to rebuild your website or application, notify your team, send a newsletter to your users, a post, a tweet, a facebook status, or re-sync your website cache..

Webhook triggers

Here is an example of a webhook body that includes every possible field that could be encountered depending on the trigger:

{
  "type": "api-update",
  "secret": "mys3cr8t!!",           // the configured secret, if any
  "masterRef" : "U_tMgS8AADQA1t37", // the new ref of the master
  "domain": "lesbonneschoses",      // your repository domain
  "apiUrl": "<https://lesbonneschoses.prismic.io/api>",
  "releases": {                   // --- CHANGES TO RELEASES
    "addition": [{                // releases that were just added
      "id": "U_sstwlGABFGWvul",
      "ref": "U_sstwlGAAxGWvum",
      "label": "A new release"
    }],
    "update": [{                  // releases that were updated
      "id": "U_ss111GABFGWvul",
      "ref": "U_sstwlG222GWvum",  // this is the new, updated ref of the release
      "label": "Some existing release"
    }],
    "deletion": [{                // deleted releases
      "id": "U_sstwlGAB333vul",
      "ref": "U_sstwlGAAxG555m",
      "label": "A not-so-important release"
    }]
  },
  "bookmarks" : {},               // --- Legacy field
  "collection": {},               // --- Legacy field
  "tags": {                       // --- CHANGES TO TAGS
    "addition": [ {               // tags that were just added
      "id": "scala"
    } ],
    "update": [],                 // tags that were updated
    "deletion": [ {               // deleted tags
      "id": "java"
    } ]
  }
}


There are now 6 events that can trigger a webhook call.

When a document is published and unpublished:

*Published and unpublished example*
{
    "type": "api-update",
    "masterRef": "XaB2ABEAABkAfET5",
    "releases": {},
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {},
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}

If you have planned releases, their ref will be updated each time you add a new document in that release.

{
    "type": "api-update",
    "masterRef": "XaBLZREAABkAe4l-",
    "releases": {
        "update": [
            {
                "id": "XZ9MwBEAABkAdylL",
                "ref": "XZ9NKBEAAA8Adysd~XaBLZREAABkAe4l-",
                "label": "test",
                "scheduledAt": 1572001200000
            },
            {
                "id": "XZ9EyREAABkAdwY0",
                "ref": "XZ9EyREAAEwAdwY1~XaBLZREAABkAe4l-",
                "label": "Halloween"
            },
            {
                "id": "XZ9LNREAABkAdyJ8",
                "ref": "XZ9LNREAADgAdyKB~XaBLZREAABkAe4l-",
                "label": "Noel"
            }
        ]
    },
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {
        "deletion": [
            {
                "id": "lala"
            }
        ]
    },
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}

When a release is created

{
    "type": "api-update",
    "releases": {
        "addition": [
            {
                "id": "XaBO3hEAABkAe5jO",
                "ref": "XaBO3hEAAEwAe5jP~XaBN7BEAABkAe5Sg",
                "label": "Paques"
            }
        ]
    },
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {},
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}

When a release is edited or deleted

{
    "type": "api-update",
    "masterRef": "XaBPIxEAABkAe5n8",
    "releases": {
        "update": [
            {
                "id": "XZ9EyREAABkAdwY0",
                "ref": "XZ9EyREAAEwAdwY1~XaBPIxEAABkAe5n8",
                "label": "Halloween"
            },
            {
                "id": "XZ9LNREAABkAdyJ8",
                "ref": "XZ9LNREAADgAdyKB~XaBPIxEAABkAe5n8",
                "label": "Noel"
            },
            {
                "id": "XaBO3hEAABkAe5jO",
                "ref": "XaBO3hEAAEwAe5jP~XaBPIxEAABkAe5n8",
                "label": "Paques"
            }
        ],
        "deletion": [
            {
                "id": "XZ9MwBEAABkAdylL",
                "ref": "XZ9NKBEAAA8Adysd~XaBN7BEAABkAe5Sg",
                "label": "test",
                "scheduledAt": 1572523200000
            }
        ]
    },
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {},
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}

{
    "type": "api-update",
    "releases": {
        "deletion": [
            {
                "id": "XaB2ghEAABkAfEc4",
                "ref": "XaB3eREAADgAfEt8~XaB3zhEAAP4_fEz2",
                "scheduledAt": 1572476400000
            }
        ]
    },
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {},
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}

When a tag is added and the related document published

{
    "type": "api-update",
    "masterRef": "XaCHNBEAAP4_fJDK",
    "releases": {},
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {
        "addition": [
            {
                "id": "wxcv"
            }
        ]
    },
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}

When a tag is deleted and the related document published

{
    "type": "api-update",
    "masterRef": "XaCHrhEAAP4_fJLq",
    "releases": {},
    "bookmarks": {},
    "masks": {},
    "collection": {},
    "tags": {
        "deletion": [
            {
                "id": "tiop"
            }
        ]
    },
    "experiments": {},
    "domain": "test-webhook-fri",
    "apiUrl": "<https://test-webhook-fri.wroom.io/api>",
    "secret": null
}


You will find a list of the most recent triggers on Webhooks ('See the logs') or in the 'Logs' tab. You’ll be able to see the event details from the past 30 days.

Determining which documents have changed

Note that this won't tell you if anything has been archived or deleted.

Configuring your webhook URL

To activate webhooks for you repository:

  • Go to Settings / Webhooks. you need to be the repository owner or to have admin rights to access it.
  • Create a new webhook. You will need to enter the webhook URL (must be reachable from the Internet) and optionally a Secret that will function as a ”password" that will be added to your webhook request. If you do this we will send the content to your server so that you can verify that the request is coming from prismic.io.

Since your URL needs to be accessible online for the Prismic webhook to reach it, it is recommended that you configure your code so that it first makes sure that the secret password is correct. If it is correct, you can then start the webhook action.

  • Select the corresponding type of triggers that you need.

Test your Webhook

Once your Webhook is added, you can trigger and test it at any time! Just click on the "Trigger it" button.

In case your server responds with anything other than a 2xx response, the delivery will be attempted every 10 minutes (up to 5 times).

You can test your Webhooks with a service like RequestBin.com

Webhooks can still be fired off for the creation of releases regardless of other settings, but you can now configure other triggers to cause the publication to fire; for example: configuring specific URLs that deal with each one.

We've mentioned a few possible usages of Webhooks, but the only limit is your imagination!

If you find a neat application for them or create a service integration, let us know. We love getting feedback and interesting use cases!

If you have any questions about these updates you can get in touch with us.

Did this answer your question?