Webhook authorized senders JSON

Background

Webhooks is a method by which one IT system can notify another IT system that data has been changed. It works by the system in which data was changed sending an HTTP request to the other system. Often the receiving system will subsequently send API requests back to the originating system to receive further details about the data.

Some webhook implementations can be abused by sending requests to unrelated third party systems. This can be used as part of a DDoS attack. An adversary can create an account on a system with a vulnerable webhook implementation and create one or more webhook configurations to send webhook requests to victim systems.

The specification in this document provides a mitigation to such attacks.

The webhook-authorized-senders.json file

The system intended to receive webhook requests MUST publish a JSON file named /.well-known/webhook-authorized-senders.json with a list of systems it wishes to receive webhook requests from. Each system is identified by a DNS name. The DNS name MAY be the domain name hosting an HTTP API used to modify the data in question.

Following is an example of what the webhook-authorized-senders.json file could look like: 

{
    "authorized-senders": [
        "example.com",
        "example.org"
    ]
}

When a user attempts to create or edit a webhook configuration, the sending system MUST verify that it is authorized by the receiving system. If the authorization fails the sending system MUST either refuse the operation or disable that webhook configuration.

The file MUST contain a single JSON object. That JSON object MUST contain a single key named authorized-senders with a value which is an array of strings.

The member name as well as the DNS names must be written in lower case. The DNS names must be fully-qualified-domain-names written without a trailing dot. Use of a * wildcard label is not permitted.

The choice to use DNS names to identification senders was purely made to utilize an existing namespace rather than invent a new namespace. There is no requirement that the DNS names identifying a sender points to the IP address of that sender. The name of the sender does not need to exist in the DNS zone, however the name being used MUST be a domain controlled by the entity responsible for the sender or a subdomain thereof.

Steps performed by webhook sender

The sender MAY reject attempts to create a webhook with a target URL using unencrypted HTTP or IP literals.

In order to authorize a receiving domain, the sending system MUST perform the following steps:

  1. Send a GET request for the /.well-known/webhook-authorized-senders.json file on the receiving domain. If the webhook target uses HTTPS the JSON file must be retrieved using HTTPS as well. If the request failed, the authorization is denied. If the URL involves an HTTP redirect the authorization SHOULD be denied.
  2. Parse the received JSON. If the parsing fails, the authorization is denied.
  3. If the received JSON is not an object or the object does not contain a member named authorized-senders the request is denied. If the contained value is not an array of strings, the request is denied. If the JSON Object contains any members with other names, those additional names MUST be ignored.
  4. Look for the name of the sending system in the array. If the name is found, the request is authorized. If the name is not found, the request is denied.

The sending system SHOULD cache the result of the authorization for at least one minute and at most 24 hours.

Refreshing authorization

The sending system MAY periodically repeat the authorization steps when the webhook configuration is used to send a webhook request. The delay between renewing authorization SHOULD be at least 15 minutes and at most 72 hours.

If the sending system performs such refreshing it MUST NOT treat transient errors in retrieval of the webhook-authorized-senders.json file as authorization failures. It is RECOMMENDED that failures to retrieve the webhook-authorized-senders.json file at this stage is treated as an outage of the receiving system and that exponential-backoff is applied. Any pending webhook requests SHOULD be queued until the outage is over.