Sitecore Experience Edge Administration and Webhooks

This is a quick start for working with the Sitecore Experience Edge Administration API and its Webhooks.

Creating Access Token

To work with the Edge you need to have an admin access token, this access token is different from the usual token that is used to access data through graphql query, it has full permission to change/delete data and manage the Experience Edge.

To Start you need to go to the https://deploy.sitecorecloud.io/. From there click on the Credential and select the Environment tab.

From Create Credential select Edge administration to create a trusted oauth client.

In the Dialog give it a meaningful Label and Description.
From the project dropdown select your project and from the environment select the environment.

After clicking the create it will show you the client id and client secret. You need to keep them in a safe place, we need these id and secret to create an access token.

Now to get an access token we need to send a POST request to the https://edge.sitecorecloud.io/oauth/token with these parameters in body:

• audience: https://api.sitecorecloud.io
• grant_type: client_credentials
• client_id: [your client id generated in previous step]
• client_secret: [your client secret generated in previous step]

Here is a sample from Thunder-Client plugin for Visual studio code with the header, content-type: application/x-www-form-urlencoded:

After posting the request, you will get the access token which can be used with admin api's:

As you can see in the scope, the access token has permission for quite few functionality, for example: edge.content:clearall

Clearing Cache

To clear the Edge cache you need to send a DELETE request to https://edge.sitecorecloud.io/api/admin/v1/cache with the access token as a bearer in the header:

and you will get 202 as the result.

Deleting all of the content

To purge/delete all contents from the edge, you can send a DELETE request to the: https://edge.sitecorecloud.io/api/admin/v1/content with including the access token:

Depending on the amount of content, it may take some time to delete everything from the edge. after it is done, you will get 202 status code.

Keep in mind you need to do full site publish to get the content in edge again.

Get Edge Setting

To get the Edge setting you need to send a GET request to https://edge.sitecorecloud.io/api/admin/v1/settings with the access token as a bearer in the header:

It will show you current cache configuration on the edge, if you want to modify them you can use PATCH request.

Creating a Webhook

The edge webhooks will give you the possibility to inform other clients about the content updates.
There are two execution modes for the webhooks:

• OnEnd: the webhook is executed at the end of the publishing job.
• OnUpdate: it also be executed at the end of publishing and includes the entity changes.

For testing your webhook you can use the https://webhook.site/ it will give you a temporary address that can be used for testing your setup.
From there copy your unique url , for example: https://webhook.site/843defab-c8ff-4431-b8f6-f6ab893ed19e.

to create a webhook you need to do a POST request to the https://edge.sitecorecloud.io/api/admin/v1/webhooks and include the body:

{
  "label": "My publish end webhook",
  "uri": "https://webhook.site/843defab-c8ff-4431-b8f6-f6ab893ed19e",
  "method": "POST",
  "headers": {
    "x-acme": "publish ended"
  },
  "body": "{\"rebuild\":\"true\", \"triggerIndex\":\"true\"}",
  "createdBy": "ga",
  "executionMode": "OnEnd"
}

After the post is done you will get the webhook object. Note down the id, you will need it later for deleting the webhook:

Now when your publish is ended a request with the headers and body configured in the webhook will be sent to the endpoint:

If you want to get the list of updated entities, you need to create a webhook with OnUpdate execution mode. Keep in mind in this mode you can not set the body anymore. The Body will have the list of updated entities

{
  "label": "ContentUpdate",
  "uri": "https://webhook.site/843defab-c8ff-4431-b8f6-f6ab893ed19e",
  "method": "POST",
  "headers": {
    "x-acme": "ContentUpdated"
  },
  "createdBy": "ga",
  "executionMode": "OnUpdate"
}

And when the publish ends, you will get the list of updated entities (Sitecore items) on the webhook target site:

Getting the list of webhooks

To get the list of existing webhooks you can simply send a GET request to the https://edge.sitecorecloud.io/api/admin/v1/webhooks, with of course included access token.

Deleting a webhook

To delete a webhook you can send a DELETE request to https://edge.sitecorecloud.io/api/admin/v1/webhooks/[Your webhook id]

and you will get 204 as the response.

Last words

the full documentation can be found here.

Thunder-client collection on Github.