Manage webhooks

Optimizely Graph exposes REST endpoints that let you register, list, and delete webhooks for your account. Use these endpoints to subscribe downstream systems to content events and to keep the subscription list aligned with your integrations as they change.

📘

Note

See the API Reference for information on managing webhooks.

🚧

Important

Authentication is required. Use either Basic or HMAC authentication.

Prerequisites

Before you register, list, or delete a webhook, confirm the following:

• An active Optimizely Graph instance with a configured source.
• Credentials for either Basic or HMAC authentication against the Optimizely Graph webhook API.
• A REST client (for example, Postman or Insomnia) or an HTTP library.
• For registration, a reachable webhook URL that accepts POST requests from Optimizely Graph.

Register a webhook with notification filters

Register a webhook to receive POST callbacks when content events match the topics and filters you define. Use this endpoint to wire up a new integration, such as a static site generator or a deploy hook.

1. Use a REST client tool, for example, Postman or Insomnia.
2. Send a POST request with the URL https://cg.optimizely.com/api/webhooks.
3. Use either Basic or HMAC authentication within the request.
4. Prepare the request body.

{
  "disabled": false,
  "request" : {
    "url" : <your_webhook_url>,
    "method": "post"
  },
  "topic": ["{subject}.{action}"],
  "filters": [ 
    { 
      [field]: { [operator]: {value} } 
    } 
  ]
}

• disabled – Boolean. Set to true to disable the webhook.
• request – Object. Represents the HTTP request to the webhook, including method (GET, POST, and so on), headers, query parameters, and body.
• topic – Array of strings. Filters events by subject and action. Use an asterisk (*) as a wildcard.
  • Examples:
    • Filter all events – topics: ["*.*"]
    • Filter all 'doc' events – topics: ["doc.*"]
    • Filter all 'updated' events – topics: ["*.updated"]
    • Filter 'doc updated' events – topics: ["doc.updated"]
    • Filter 'doc updated' or 'bulk completed' events – topics: ["doc.updated", "bulk.completed"]
  • Available values for subject:
    • doc – For updating events involving only a single content.
    • bulk – For updating events involving multiple content in one request.
    • * – Update both event types, doc and bulk.
      • If you are not sure, use * for the subject.
• (Optional) Filters property – An object containing key-value pairs, where each key is a filter name, and the value is an array of filter objects. Filters help you receive specific notifications.
  The following examples show different filter configurations:
  • Filters docs that have 'Published' status.
    JSON

     {
       "request" : {
          "url" : <your_webhook_url>,
          "method": "post"
       },
       "filters": [
         { "status": { "eq": "Published" } }
       ],
     }

  • Filters docs that have 'Published' or 'Draft' status.
    JSON

    {
       "request" : {
          "url" : <your_webhook_url>,
          "method": "post"
       },
       "filters": [
         { "status": { "eq": "Published" } },
         { "status": { "eq": "Draft" } }
       ],
    }

  • Filters docs that have 'Published' status and id '123'.
    JSON

     {
       "request" : {
          "url" : <your_webhook_url>,
          "method": "post"
       },
       "filters": [
         {
           "status": { "eq": "Published" },
           "id": { "eq": "123" }
         }
       ]
     }

  • Filters docs that have custom fields like 'siteId' (for example, with multiple sites).

    📘

    Note

    Custom fields are case-sensitive.

    JSON

     {
       "request" : {
          "url" : <your_webhook_url>,
          "method": "post"
       },
       "filters": [
         {
           "siteId": { "eq": "site_id" }
         }
       ]
     }

  • Filters docs that have custom fields like page name and 'Published' status (assume that the page name is not changed).
    JSON

    {
      "request" : {
         "url" : <your_webhook_url>,
         "method": "post"
      },
      "filters": [
        {
          "Name": { "eq": "Alloy Plan" },
          "status": { "eq": "Published" }
        }
      ]
    }

List all registered webhooks

List the registered webhooks for your account to review which subscriptions are active and to retrieve the ID required to delete or update a webhook.

1. Open your REST client.
2. Send a GET request with the URL https://cg.optimizely.com/api/webhooks.
3. Use either Basic or HMAC authentication within the request.

The following example shows a response:

[
  {
    "id": <guid>,
    "request" : {
      "url" : <your_webhook_url>,
      "method": "post"
    },
    "filters": [
      {
        "status": { "eq": "Published" }
      }
    ]
  }
]

Delete a registered webhook

Delete a webhook to stop receiving callbacks when an integration is decommissioned or when you want to replace a subscription with a new configuration.

1. List the registered webhooks (see List all registered webhooks) and copy the ID of the webhook to delete.
2. Send a DELETE request with the URL https://cg.optimizely.com/api/webhooks/{id}, where {id} is the ID of the registered webhook.
3. Use either Basic or HMAC authentication within the request.