Manage webhooks

Optimizely Graph provides endpoints to manage your webhooks for a specific account.

📘

Note

See the API Reference for information on managing webhooks.

🚧

Important

Authentication required, use either Basic or HMAC authentication.

Register a webhook with notification filters

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 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.
  • Available values for subject and action.
    • doc – For updating events involving only a single content.
      • updated – For updating the event involving.
    • bulk – For updating events involving multiple content in one request.
      • completed – All contents in bulk are processed.
    • * – Update both event types, doc and bulk.
      • If you are not sure, use * for the subject.
  • 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"]
  • (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 names of the fields in the filter will match the field names in Optimizely Graph query.
    • Webhooks only Support two operations for filter conditions: eq and in.
      • eq: compares equal to a value.
        JSON

         {
           "filters": [
             {
               "status": { "eq": "Published" }
             }
           ]
         }
        

        in: the field value is one of the values in the array.
        JSON

          {
           "filters": [
             {
               "status": { "in": ["Published","Draft"] }
             }
           ]
         }
        

    • Examples:
      • If the field to filter is a nested field, "." is used to separate the levels.
        JSON

        {
          "filters": [
            {
              "ContentLink.GuidValue": { "eq": "2e49372f-7795-4ab4-a2b0-bc4d4884d8d4" }
            }
          ]
        }
        

        
        
      • Filters docs that have 'Published' status.
        JSON

         {
           "filters": [
             { "status": { "eq": "Published" } }
           ],
         }
        

      • If the array of filter objects contains more than one object, the condition to receive a notification is an OR condition.
        • Filters docs that have 'Published' or 'Draft' status.
          JSON

          {
             "filters": [
               { "status": { "eq": "Published" } },
               { "status": { "eq": "Draft" } }
             ],
          }
          

      • If a single object contains more than one condition, the condition to receive a notification is an AND condition.
        • Filters docs that have 'Published' status and ID '123'.
          JSON

          {  
                 "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

         {
           "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

        {
          "filters": [
            {
              "Name": { "eq": "Alloy Plan" },
              "status": { "eq": "Published" }
            }
          ]
        }
        

• Registering webhook examples
  • Filters docs that have 'Published' status.
    JSON

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

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

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

  • Filters docs that have ' 7c2af0d1-6059-4622-97f8-e9b108f23293' GuidValue.
    JSON

    {
       "request" : {
          "url" : <your_webhook_url>,
          "method": "post"
       },
       "topic": ["*.*"],
       "filters": [
         "ContentLink.GuidValue": { "eq": "7c2af0d1-6059-4622-97f8-e9b108f23293" }
       ],
    }
    

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

    {
       "request" : {
          "url" : <your_webhook_url>,
          "method": "post"
       },
       "topic": ["*.*"],
       "filters": [
         "status": { "in": ["Published","Draft"] }
       ],
    }
    

    
    

Registered webhooks

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

Example response:

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

Delete a registered webhook

1. Use a REST client tool to list all webhooks and get the ID of the webhook you want to delete.
2. Send a DELETE request with the URL: https://cg.optimizely.com/api/webhooks/{id} (ID of registered webhook).
3. Use Basic or HMAC authentication within the request.