Webhook’s Cast Target Service #

This document is for developers.

Overview #

Cast Target Service is a destination of the Webhook Cast, designated by the URL of the Cast’s action.

This document provides information for developers of Cast Target Service.

Requirements #

In this section, we describe the requirements of Cast Target Services.

Basic requirements #

It is RECOMMENDED that the URL scheme is https.

Actcast sends two types of HTTP requests to URLs given by users.

• Cast request: Actcast aggregates Act Logs sent by devices and sends them to Cast Target Service. HTTP method depends on the configuration of the Cast.
• get-actcast-option request: Request to get Actcast option: For details, see below Actcast option.

For each request, HTTP headers are attached as you configured in your Cast setting.

Ordinally, Casts are used to notify something detected, or record detected data. In other words, the purpose is a side-effect. Therefore, users and Cast Target Service SHOULD use the HTTP method POST. (For example, see RFC9205 4.5.1. for the reason we shouldn’t use GET.)

If Cast Target Services returned an error response with HTTP status code 4xx/5xx, Actcast drops the request and records the status code.

Your Cast Target Service SHOULD ensure that only permitted users can get information to configure a Cast, such as URL and HTTP headers. See also Authentication.

Several users can specify the same URL as their Cast targets. Actcast sends Cast requests by the configurations. Therefore, Cast Target Service MUST NOT limit sending Cast (e.g. rate-limiting) only by the information of client such as IP, domain, etc. If it is necessary, Cast Target Service MUST limit by using more fine-grained information, described in Authentication.

Actcast option #

Cast Target Services can tell their configuration for Actcast to Actcast. This configuration is called the “Actcast option”.

For example, assume that you provide a service that stores all Casts to analyze. By default, rate-limiting drops exceeded Casts to reduce the load of the Cast Target Service. (Rate limit of Webhook Cast) This Cast Target Service should tell Actcast not to do rate-limiting to get all Casts. Actcast option realizes this.

Actcast retrieves the Actcast option for each Cast. Cast Target Service MAY return different Actcast options per authentication as in Authentication.

get-actcast-option request #

Actcast retrieves the Actcast option by sending get-actcast-option request to a Cast Target Service. It is RECOMMENDED that the Cast Target Service responds correctly to the get-actcast-option request.

Note that Actcast can send get-actcast-option requests as users use the URL of your service even if your service does not declare the Actcast option. Actcast uses a default value if the service doesn’t respond correctly.

Below are requirements to use the Actcast option.

URL scheme MUST be https.

HTTP method of get-actcast-option request is GET. Cast Target Services should follow the below:

• The service MUST return a response with a header x-actcast-option: <base64-actcast-opiton> regardless HTTP status code.
  • <base64-actcast-option> is base64-encoded string of <actcast-option>.
  • <actcast-option> is UTF-8 JSON string as described in the next section.

Actcast sends get-actcast-option request only when the user saves the configuration of the Cast so far. Users must edit configuration again if the Cast Target Service changed the Actcast option.

<actcast-option> #

<actcast-option> is a JSON like the following.

{
    "version": "1.0",
    "accept_ratelimit_removal": true
}

Additionally, the string encoded in base64 is ewogICAgInZlcnNpb24iOiAiMS4wIiwKICAgICJhY2NlcHRfcmF0ZWxpbWl0X3JlbW92YWwiOiB0cnVlCn0=.

Each field has the following meaning:

Techniques #

This section describes useful techniques to develop Cast Target Services.

Authentication #

Users of Actcsat can use arbitrary URLs for Casts. Actcast cannot check that the user is permitted to send requests to the URL. This is done by Cast Target Service itself: Authenticating HTTP requests.

Typical patterns are the followings:

Issue a URL unguessable by outsiders #

Issue a URL like

https://example.com/cast-target/very-loooooooooooooooooooong-and-unguessable-url-dmVyeS1sb29vb29vb29vb29vb29vb29vb29uZy1hbmQtdW5ndWVzc2FibGUtdXJs

as the user requested. Issuing unguessable URLs prevents outsiders use the URLs for the Cast.

Authenticate by HTTP header #

Users can set HTTP header for Cast together with URL. For more details, see MDN Web Docs, HTTP authentication.