Configuring Listener Endpoints

Organizations must configure and maintain their own webhook endpoints: Akamai will send you event notifications, but it’s up to you to figure out how to receive and process those notifications. (Fortunately, there are innumerable libraries and SDKs available that make this process relatively easy.) Akamai’s only requirements are:

  • Your webhooks endpoint must be public-facing, and must have a publicly-accessible IP address. Webhooks v3 resolves the domain during configuration, and the resolved address must pass validation (for example, an ALIAS to 127.0.0.1 will be rejected as an invalid address). If you are using Amazon Web Services in the same region as as your webhooks implementation, your endpoint will likely resolve to a private IP address; that private IP address will be rejected by the Webhooks API.  In that case, you'll need to create a publicly-facing endpoint. for use with Webhooks v3

    Your webhooks endpoint must use HTTPS. If you try to create a webhooks subscription that references an HTTP endpoint your API call will fail and the subscription won’t be created.
  • Your webhooks endpoint must have a valid SSL certificate from a public Certificate Authority. Webhooks can only be transmitted across networks using TLS 1.2 or later.
     
  • Your webhooks endpoint must respond to POST requests by using standard HTTP status codes. If Webhooks v3 receives a non-HTTPS response it will typically mark the delivery as a failure and make no effort to redeliver the notification.

In addition to requiring HTTPS, Akamai also maintains a block list of domain names and IP addresses that cannot be used when configuring a webhooks endpoint: if you try to use a blocked domain name or IP address when setting up a webhooks subscription your API call will fail. The following table lists several blocked domains/IP addresses:

Description

Domain Name

IPv4 Example

IPv6 Example

Local addresses

localhost

127.0.0.0/8

::1/128

Private IPv4 addresses

--

10.0.0.0/8

--

Private IPv6 addresses

--

--

::1/128

Link-local addresses

--

169.254.0.0/16

fe80::/10

It’s not hard to see why these domains and IP addresses are prohibited: after all, what would a webhooks dispatcher do if it was asked to send an event notification to https://localhost? Any attempt to use one of the above domains or IP addresses when configuring a webhooks subscription results in failure:

Note. Webhooks v3 verifies that an endpoint is accessible before it allows you to use that endpoint in a webhooks subscription. For example, suppose your webhooks listener is located at https://mywebhooks.listener.com, but you accidentally mistype that as https://mywebhooks.listener.cob. Webhooks will attempt to reach https://mywebhooks.listener.cob and, when that attempt fails, the API call for creating the subscription also fails.

Other than that, there are relatively few restrictions on endpoint URLs. For example, any of the following URL variations are acceptable:

Description

Example

Domain-only URL

https://documentation.akamai.com

URL with path

https://documentation.akamai.com/webhook/endpoint

URL with custom port number

https://documentation.akamai.com:444

URL with query parameters

https://documentation.akamai.com/webhook/endpoint?foo=bar&qux=baz

URL with custom port number and query parameters

https://documentation.akamai.com:444/webhook/endpoint?foo=bar&qux=baz

It’s also important that your endpoint respond to requests in a timely fashion (i.e., 500 milliseconds or less). Suppose Webhooks v3 tries to deliver Event A to your listener endpoint. The endpoint accepts the request and Event A is delivered; however, the response is delayed. As a result, Webhooks v3 times out and assumes that delivery failed. Consequently, Webhooks v3 schedules Event A for redelivery, meaning that you could end up with duplicate events: one Event A that was delivered but not marked as a successful delivery, and a duplicate Event A sent during the redelivery attempt.

One way to help guard against this problem? Make sure that any custom event processing you need to do takes place after event delivery and receipt. For example, you might want to add custom information to each event when it gets written your organization’s database. That’s fine: just make sure that you acknowledge receipt of the event first and then add the custom information. Any sort of event customization should take place as a completely separate process from event receipt.