Webhooks

Learn about webhooks; used to create automation workflows when you create, update, and delete content using the Cosmic dashboard and API.

Creating webhooks

Go to Bucket Settings > Webhooks to create a new webhook. Give your webhook a URL, title, properties to return, custom headers, and select the events you want to listen for on a given resource. See the dashboard reference for webhooks for more information on creating webhooks in the dashboard.

When webhooks are activated, whenever an event happens in the dashboard or API, a webhook is sent by Cosmic to the indicated URL as a POST request. See section below for possible event types and payload example.

The webhook model

The webhook response model contains all the information about the webhook response.

Properties

• Name resource Type enum Description
  The resource that received the action.

  Options objects | media

• Name event Type enum Description
  The event that occurred.

  Options created | edited | deleted

• Name triggered_at Type number Description
  The time the event was triggered (in UTC milliseconds).

• Name data Type object Description
  The payload that you define in the dashboard using props. Optional.

Consuming webhooks

When your app receives a webhook request from Cosmic, check the resource and event property to see what event occurred.

Using props

You can specify which props you would like to include in the data property (if any). For example, this is the payload you would receive when a new object is created and published with the props of slug,title,type,status,metadata included.

Example payload

{
  "resource": "objects",
  "event": "created",
  "triggered_at": 1576861549889,
  "data": {
    "object": {
      "slug": "cosmic-webhooks-rock",
      "title": "Cosmic webhooks rock",
      "type": "blog-posts",
      "status": "published",
      "metadata": {
        "content": "<p>Cosmic webhooks enable me to communicate with third-party APIs automatically when I update content in my Cosmic Bucket, sweet!</p>",
        "headline": "Cosmic webhooks are AMAZING!",
        "emoji": "🚀"
      }
    }
  }
}

Custom headers

You can also include custom headers to send any custom information, or for an added layer of security. For example, when verifying the request using a secret key.

Verifying a request

const secret = req.headers['super-secret-key'];

if (secret === process.env.SUPER_SECRET_KEY) {
  // Request is verified
} else {
  // Request could not be verified
}

If the super-secret-key value in the custom header you created matches the one in your environment variable you can be sure that the request was truly coming from Cosmic.

Testing webhooks

You can use a service like Beeceptor to test your webhooks and view response data.