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 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 nu further effort to deliver 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:

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:

📘

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:

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 another delivery try, meaning 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.

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.

Webhooks v3 Server IP address allow lists

Because the Webhooks v3 cloud-based infrastructure runs on Amazon Web Services, there’s no simple way of creating an allow list of server IP addresses: after all, individual servers can come and go at any time, and IP addresses can appear and reappear seemingly at random. To be on the safe side, you’d have to place the entire range of IP addresses allocated to the ​Akamai​ Identity Cloud on the allow list.

If you’re concerned about verifying the validly of event notifications, a better approach might be to verify the signature on each notification: if the signature is valid then the notification is valid.