Skip to content

Latest commit

 

History

History
90 lines (57 loc) · 4.06 KB

2.aem-event-webhooks.md

File metadata and controls

90 lines (57 loc) · 4.06 KB

Register the AEM event consumer app

To register an AEM event consumer app, you just need a publicly available endpoint, we call a webhook.

Your webhook

Before you can register a webhook, the webhook needs to be online and operational. If not, then the registration will fail. So you need to take care of setting that up first. Your webhook must be hosted on a server. For development, you may use localhost along with a tool like ngrok.

Your webhook needs to

  • be accessible from the internet (localhost won't work)
  • be reachable over HTTPS
  • correctly respond to a "challenge" request

The challenge request

When registering a webhook, Adobe I/O Events will first try to verify that the URL is valid. To do this, it sends an HTTP GET request, with a challenge query parameter. The webhook should respond with a body containing the value of the challenge query parameter.

GET https://acme.example.com?challenge=8ec8d794-e0ab-42df-9017-e3dada8e84f7

Response

You can either respond by placing the challenge value directly in the response body:

HTTP/1.1 200 OK

"8ec8d794-e0ab-42df-9017-e3dada8e84f7"

or by responding with a JSON object, including the correct content-type header:

HTTP/1.1 200 OK
Content-type: application/json

{"challenge":"8ec8d794-e0ab-42df-9017-e3dada8e84f7"}

Authenticating events

Your webhook URL must by necessity be accessible from the open internet. This means third-party actors can send forged requests to it, tricking your application into handling fake events.

To prevent this from happening, Adobe I/O Events will add a x-adobe-signature header to each POST request it does to your webhook URL, which allows you to verify that the request was really made by Adobe I/O Events.

This signature or “message authentication code” is computed using a cryptographic hash function and a secret key applied to the body of the HTTP request.

In particular, a SHA256 HMAC is computed of the JSON payload, using your client secret as a secret key, and then turned into a Base64 digest.

Upon receiving a request, you should repeat this calculation and compare the result to the value in the x-adobe-signature header, and reject the request unless they match. Since the client secret is known only by you and Adobe I/O Events, this is a reliable way to verify the authenticity of the request.

More details here

Create your webhook:

We propose here to create your webhook either

About ngrok

Ngrok is a utility for enabling secure introspectable tunnels to your localhost. With ngrok, you can securely expose a local web server to the internet and run your own personal web services from your own machine, safely encrypted behind your local NAT or firewall.

With ngrok, you can iterate quickly without redeploying your app or affecting your customers.

Among other things, ngrok is a great tool for testing webhooks. Once you've downloaded and installed ngrok, you run it from a command line, specifying the protocol and port you want to monitor: ngrok http 80

In the ngrok UI, you can see the URL for viewing the ngrok logs, labeled "Web Interface", plus the public-facing URLs ngrok generates to forward HTTP and HTTPS traffic to your localhost. You can use either of those public-facing URLs to register your Webhook with Adobe I/O, so long as your application is configured to respond on your localhost accordingly. Once your testing phase is complete, you can replace the ngrok URL in your Adobe I/O integration with the public URL for your deployed app.