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 occured.


    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 occured.

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.

FAQ

What fields are on the payload?

resource, event, triggered_at, and data. Create the webhook in Bucket Settings > Webhooks. You can add a custom header and check it in your handler.

How do I revalidate a SvelteKit site?

A route that checks the header and reads resource and event is at https://www.cosmicjs.com/docs/how-to/webhooks-sveltekit.md.

How much does Cosmic cost?

Project plans are Free ($0), Builder ($99/mo), Team ($299/mo), Business ($499/mo), Enterprise (custom pricing). Yearly billing saves 10%. Workspace plans are Small Workspace ($999/mo) and Large Workspace ($2,999/mo), and they start with a 30-day free trial. Allowances, add-on rates, and the rest of the pricing FAQ are plain text at https://www.cosmicjs.com/pricing.md.

Are API keys required, and is content private?

Each Bucket has a read key and a write key in Bucket Settings > API Access. GET requests use the read key. POST, PATCH, and DELETE use the write key as Authorization: Bearer. Do not put the write key in a browser bundle, a mobile app, or a NEXT_PUBLIC_ variable. SAML single sign-on is on Large Workspace and Enterprise. The audit log is append-only. Text versions: https://www.cosmicjs.com/security.md and https://www.cosmicjs.com/docs/dashboard/audit-log.md.

Can an agent create a Cosmic project without an existing account?

Yes. POST https://dapi.cosmicjs.com/v3/agents/sign-up provisions a free-tier project and bucket tied to a human email, with no existing Cosmic account. The human claims it with the emailed one-time code. The playbook is https://www.cosmicjs.com/docs/ai-onboarding.md.