Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In

Register Webhooks

To register a webhook, you will need to provide the following information

  • Callback URL – A valid URL where Optimizely sends the HTTP POST requests. URL may contain subdomains, paths, sub-paths and query strings. Using HTTPS is mandatory.
  • Event names – Events to which you want to subscribe. You can subscribe to one or multiple events against a callback URL.
  • Secret (optional) – You can provide a secret (random string up to 32 character) while registering a webhook. If provided, Optimizely sends the secret with the HTTP POST request in the Callback-Secret header when triggering the webhook event. When you receive the event in your callback URL, you can validate the secret from the Callback-Secret header.

Backward compatibility

The following changes are considered to be backward compatible:

  • Add a new field to the webhook payload
  • Add a value to an enum
  • Add a new request header

Experimental Webhooks

Some documents may have a banner indicating experimental webhooks.

Experimental webhooks provide early access to APIs that are currently under development so that you have early access, can plan for implementing, and provide feedback.

The documentation may highlight new features, new data properties and data models, new filters, and other features specific to the new API.

These webhooks are most often NOT operational and the documentation is subject to change until the APIs are fully released.

Experimental webhooks generally require testing and development on your own applications before relying on them in your stable production environments.

Event delivery

Delivery sequence

Optimizely Content Marketing Platform (CMP) does not guarantee the delivery of events in the sequence in which they are generated. You can use the Optimizely Content Marketing Platform Open API to fetch the latest data.


When you receive an event, acknowledge the delivery by returning an HTTP 200 or 202 status code. Anything other than 200 or 202 is considered a delivery failure.


It is expected that the callback endpoint will respond within 10 seconds of receiving the webhook event. If it takes more then 10 seconds, the connection is terminated and will be considered a delivery failure.


In case of delivery failure, Optimizely Content Marketing Platform (CMP) retries to deliver the event for up to three days with an exponential back off.

Duplicate events

In rare cases, callback endpoints might receive the same event more than once. Make your event processing idempotent to guard against duplicated events.

If you make multiple identical requests and receive the same response every time, the APIs are generally called idempotent. Some API consumers knowingly or unknowingly make the same request twice or thrice. The APIs have to understand this and reply with the same response.