Webhook
Webhook provides an interface to post events that occur when sending or receiving email to the specified endpoint via HTTP.
Version
The format of POST parameters and response messages differs depending on the API version. Please refer to the API specifications of the version you use.
Current version is 2.
Common Specification
Common specification of the Webhook will be explained in this section.
| Item | Value |
|---|---|
| Protocol | HTTPS |
| Character code | UTF-8 |
| Newline code | LF |
Endpoint
An endpoint points to URL that receives an HTTP request.
Webhook,implemented by the customer,posts event data such as email reception and mail delivery status to the endpoint Settings in the management GUI.
Authentication
Authentication function that use BASIC authentication or API key can be implemented on the endpoint side for HTTP requests sent by webhook.
HTTP Request
HTTP request specifications sent by the Webhook will be explained in this section.
Version
Webhook HTTP requests are compatible with the following versions:
| Item | Correspondence situation and version |
|---|---|
| SSL/TLS version | TLS1.1, TLS1.2 are supported |
| HTTP version | HTTP/1.1 is supported |
Method
Webhook only send POST methods.
Header
The webhook sends the following header fields:
| Header Field | Description |
|---|---|
| content-length | Size of POST data |
| content-type | Content type of the POST data.See MIME type below. |
| host | Host name and port number of the POST destination server (example: endpoint.example.com:443) |
| connection | Keep-Alive |
| user-agent | Character string send HttpClient. |
| accept-encoding | gzip, deflate |
| authorization | Sends user authentication data and Bearer tokens for BASIC authentication. |
MIME Type
The endpoint must handle HTTP requests appropriately depending on the encoding type.
The encoding type of the Event Webhook that notifies the mail delivery status is application/x-www-form-urlencoded.
application/json can be used by setting "use JSON format" in Settings of the management console.
The encoding type of the Inbound Webhook that notifies you of receiving an email is multipart/form-data (to handle attachment file).
application/json can be used by setting "use JSON format" in Settings of the management console.
Warning
If you use application/json with an inbound webhook, you will not be notified of email attachments.
Parameter
Webhook includes api_key for authentication in all HTTP requests and send sthe parameters defined for each URL.
This document describes the parameters according to the following format.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| api_key | Yes | ASCII | Secret key used for user authentication. |
| server_composition | Yes | UTF-8 | name of the server configuration that will be operated (Please refer to here) for server configuration |
- Parameter: The name of the parameter to POST.
- Required: If this parameter is required, Yes.
- Data Type: Data type of the parameter value.（Refer to below Data Type）
- Description: Description about this parameter.
For parameters with restrictions such as default value and value range, record in the following format in the description column.
- Default: (default value)
- Span: min=(minimum value) / max=(maximum value)
- Restrictions: Description about the restrictions on parameters.
The size of the data can be POSTed is up to 2MByte.
Data Type
Webhook handles data types according to the following specifications.
| Data Type | Description |
|---|---|
| UTF-8 | Represents multibyte characters, including ASCII. |
| ASCII | Represents printable ASCII characters. |
| INTEGER | Represents a number in the range -2147483648 to 2147483647. |
| DATE | Represents a date in YYYY-MM-DD format. |
| TIME | In HH:mm:ss format, the hours, minutes, and seconds are expressed in 24-hour notation. |
| DATETIME | Represents the date and hour in YYYY-MM-DD HH:mm:ss format. |
| BOOLEAN | Represents either 'true' or 'false'. |
HTTP Response
HTTP response specifications received by the endpoint will be explained in this section.
Status Code
The webhook works as follows depending on the HTTP status code that the endpoint responded to.
| Code | Action |
|---|---|
| 200 | The request is considered to have been processed normally and ends normally. |
| 4xx | If 401, 407, 408 is returned, it is considered an authentication error or a temporary error and an attempt is made to resend the event. If any other status code in the 400s is returned, the error process terminates. |
| 5xx | If 502, 503, 504 is returned, it is considered a temporary error on the endpoint or reverse proxy and attempts to resend the event. If any other status code in the 500s is returned, the error process terminates. |
Header
Webhooks do not reference HTTP response headers.
Message
Webhooks do not reference HTTP response body.