# HTTP
The HTTPS (`http`) action sends data from an MQTT message to an HTTPS endpoint, which can point to a web application or service.
## Requirements
This rule action has the following requirements:
+ You must confirm and enable HTTPS endpoints before the rules engine can use them. For more information, see [HTTP action destinations](http-action-destination.md).
## Parameters
When you create an AWS IoT rule with this action, you must specify the following information:
`url`
The HTTPS endpoint where the message is sent using the HTTP POST method. If you use an IP address in place of a hostname, it must be an IPv4 address. IPv6 addresses are not supported.
Supports [substitution templates](iot-substitution-templates.md): Yes
`confirmationUrl`
(Optional) If specified, AWS IoT uses the confirmation URL to create a matching topic rule destination. You must enable the HTTP action destination before using it in an HTTP action. For more information, see [HTTP action destinations](http-action-destination.md). If you use substitution templates, you must manually create an HTTP action destination before the `http` action can be used. `confirmationUrl` must be a prefix of `url`.
The relationship between `url` and `confirmationUrl` is described by the following:
+ If `url` is hardcoded and `confirmationUrl` is not provided, we implicitly treat the `url` field as the `confirmationUrl`. AWS IoT creates a topic rule destination for `url`.
+ If `url` and `confirmationUrl` are hardcoded, `url` must begin with `confirmationUrl`. AWS IoT creates a topic rule destination for `confirmationUrl`.
+ If `url` contains a substitution template, you must specify `confirmationUrl` and `url` must begin with `confirmationUrl`. If `confirmationUrl` contains substitution templates, you must manually create an HTTP action destination before the `http` action can be used. If `confirmationUrl` does not contain substitution templates, AWS IoT creates a topic rule destination for `confirmationUrl`.
Supports [substitution templates](iot-substitution-templates.md): Yes
`headers`
(Optional) The list of headers to include in HTTP requests to the endpoint. Each header must contain the following information:
`key`
The key of the header.
Supports [substitution templates](iot-substitution-templates.md): No
`value`
The value of the header.
Supports [substitution templates](iot-substitution-templates.md): Yes
The default content type is application/json when the payload is in JSON format. Otherwise, it is application/octet-stream. You can overwrite it by specifying the exact content type in the header with the key content-type (case insensitive).
`auth`
(Optional) The authentication used by the rules engine to connect to the endpoint URL specified in the `url` argument. Currently, Signature Version 4 is the only supported authentication type. For more information, see [HTTP Authorization](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html).
Supports [substitution templates](iot-substitution-templates.md): No
`enableBatching`
(Optional) Whether to process the HTTP action messages into a single request for a given url. Value can be true or false. For more information on batching, see [Batching HTTP action messages](http_batching.md).
Boolean value
Supports [substitution templates](iot-substitution-templates.md): No
`batchConfig`
(Optional) Configuration settings for batching. Once enabled, `batchConfig` parameters must be specified. If `batchConfig` parameters are not specified, the default values will be used.
`maxBatchOpenMs`
The maximum amount of time (in milliseconds) an outgoing message waits for other messages to create the batch. The higher the setting, the longer the latency of the batched HTTP action.
Minimum Value: 5 ms. Maximum Value: 200 ms.
Default Value: 20 ms
Supports [substitution templates](iot-substitution-templates.md): No
`maxBatchSize`
The maximum number of messages that are batched together in a single action execution.
Supports [substitution templates](iot-substitution-templates.md): No
Minimum Value: 2 messages. Maximum Value: 10 messages
Default Value: 10 messages
`maxBatchSizeBytes`
Maximum size of a message batch, in bytes.
Minimum Value: 100 bytes. Maximum Value: 131,072 bytes
Default Value: 5,120 bytes
Supports [substitution templates](iot-substitution-templates.md): No
The default content type is application/json when the payload is in JSON format. Otherwise, it is application/octet-stream. You can overwrite it by specifying the exact content type in the header with the key content-type (case insensitive).
## Examples
The following JSON example defines an AWS IoT rule with an HTTP action.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## HTTP action retry logic
The AWS IoT rules engine retries the HTTP action according to these rules:
+ The rules engine tries to send a message at least once.
+ The rules engine retries at most twice. The maximum number of tries is three.
+ The rules engine does not attempt a retry if:
+ The previous try provided a response larger than 16,384 bytes.
+ The downstream web service or application closes the TCP connection after the try.
+ The total time to complete a request with retries exceeded the request timeout limit.
+ The request returns an HTTP status code other than 429, 500-599.
**Note**
[Standard data transfer costs](https://aws.amazon.com/ec2/pricing/on-demand/) apply to retries.
## See also
+ [Batching HTTP action messages](http_batching.md)
+ [HTTP action destinations](http-action-destination.md)
+ [Route data directly from AWS IoT Core to your web services](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/) in the *Internet of Things on AWS* blog
# Batching HTTP action messages
You can use batching to send multiple HTTP action messages in a single request.
## Overview
Batching enables you to send messages from AWS IoT Core Rules Engine to your HTTP endpoints in batches. This functionality can help reduce your costs by lowering the number of HTTP action executions as well as improve efficiency by reducing the overhead associated with establishing new connections.
**Note**
The batched HTTP action is metered as a single action. You are metered in increments of 5 kiB, based on the size of outbound batched payload emitted by the AWS IoT Core Rules Engine to the downstream service. For more information, see the [AWS IoT Core pricing page](https://aws.amazon.com/iot-core/pricing/).
When you enable batching in the definition of your IoT Rule Action, the following parameters will be available for configuration:
`maxBatchOpenMs`
The maximum amount of time (in milliseconds) an outgoing message waits for other messages to create the batch. The higher the setting, the longer the latency of the batched HTTP action.
Minimum Value: 5 ms. Maximum Value: 200 ms.
Default Value: 20 ms
Supports [substitution templates](iot-substitution-templates.md): No
`maxBatchSize`
The maximum number of messages that are batched together in a single IoT rule action execution.
Minimum Value: 2 messages. Maximum Value: 10 messages
Default Value: 10 messages
Supports [substitution templates](iot-substitution-templates.md): No
`maxBatchSizeBytes`
Maximum size of a message batch, in bytes.
Minimum Value: 100 bytes. Maximum Value: 131,072 bytes
Default Value: 5120 bytes
Supports [substitution templates](iot-substitution-templates.md): No
**Important**
When you specify multiple batch parameters, batching completes when the first limit is reached. For example, if you specify 100 ms as the Maximum Batch Open Time and 5 kiB as the Maximum Batch Size, and Rules Engine batches only 2 kiB within 100 ms, then a 2 kiB batch will be created and sent.
## Using HTTP headers in a batch
When you use headers in your HTTP action, the batched request uses the header value from the last message that was added to the batch (not necessarily the last message you published). We recommend using header values that are either:
+ Identical across all messages in the batch
+ Applicable to all messages (for example, authentication credentials)
The headers are sent with the HTTP request and are not part of the message body.
**Note**
When batching is enabled:
The batched request automatically includes the `Content-Type: application/json` header, as the batch is sent as a JSON array.
We can't guarantee that the last message in the batch is the last message that you published. It is the last message that made it into the batch.
## Payload Example
The following example shows the structure of a batched message payload sent to your HTTP endpoint:
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## Limitations
The following are limitations on batching:
+ AWS IoT Core does not guarantee overall message ordering. Batching is performed locally on each host, which may result in messages within a batch being processed in a different order than they were received.
+ AWS IoT Core does not provide message processing support on the receiver side. You are responsible for ensuring that your downstream service is configured to accept and process data in batches.
+ Cross-account batching is not supported, even if messages are destined for the same resource identifier (HTTP URL or resource ARN).
+ AWS IoT Core does not guarantee that the batch size will meet the configuration you specified. Batches may be smaller than your configured limits based on timing and message flow.
+ When batching is enabled, binary payloads (non-UTF-8 data) are not supported. Only UTF-8 text payloads (such as JSON) are accepted. To send binary data, base64 encode it before sending it to the HTTP action, and then decode it at your receiving endpoint. For example, you can use the [encode function](iot-sql-functions.html#iot-function-encode) in IoT rules to encode the binary payload. Alternatively, you can encode the binary payload in your IoT device and publish it to AWS IoT Core.
## Error Actions for Batching
You will not be able to define a separate batching logic in your Error Action definition. However, your Error Action will support batching if you have defined batching logic in your primary Action.
When a batch request fails, AWS IoT Core Rules engine will follow the [HTTP action retry logic](https-rule-action.md#https-rule-action-retry-logic). After the final retry attempt, an error action will be invoked for the entire failed batch.
The following is an example of an error action message with batching enabled:
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**Note**
Batched action failures also generate larger error action payloads which can increase the probability of error action failures due to size. You can monitor error action failures using the `ErrorActionFailure` metric. See [Rule action metrics](metrics_dimensions.md#rule-action-metrics) for more information.
## Batching HTTP action messages with the AWS CLI
### Creating or updating a rule action with batching
1. Use the appropriate AWS CLI command to create or update a rule:
+ To create a new rule, use the [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) command:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ To update an existing rule, use the [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html) command:
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. Enable batching capabilities by setting the enableBatching parameter to true in your topic rule payload:
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. Configure the batching parameters. You do not need to specify all batch parameters. You can choose to specify 1, 2, or all 3 batch parameters. If you do not specify a batch parameter, Rules Engine will update that parameter with the default values. For more information on batching parameters and their default values, see [HTTP parameters](https-rule-action.md#https-rule-action-parameters).
# HTTP action destinations
An HTTP action destination is a web service to which the rules engine can route data from a topic rule. An AWS IoT Core resource describes the web service for AWS IoT. Destination resources can be shared by different rules.
Before AWS IoT Core can send data to another web service, it must confirm that it can access the service's endpoint.
## Overview
An HTTP action destination refers to a web service that supports a confirmation URL and one or more data collection URLs. The destination resource contains the confirmation URL of your web service. When you configure an HTTP action, you specify the actual URL of the endpoint that should receive the data along with the web service's confirmation URL. After your destination is confirmed, the topic rule sends the result of the SQL statement to the HTTPS endpoint (and not to the confirmation URL).
An HTTP action destination can be in one of the following states:
ENABLED
The destination has been confirmed and can be used by a rule action. A destination must be in the `ENABLED` state for it to be used in a rule. You can only enable a destination that's in DISABLED status.
DISABLED
The destination has been confirmed but it can't be used by a rule action. This is useful if you want to temporarily prevent traffic to your endpoint without having to go through the confirmation process again. You can only disable a destination that's in ENABLED status.
IN\$1PROGRESS
Confirmation of the destination is in progress.
ERROR
Destination confirmation timed out.
After an HTTP action destination has been confirmed and enabled, it can be used with any rule in your account.
## Managing HTTP action destinations
You can use the following operations to manage your HTTP action destinations.
### Creating HTTP action destinations
You create an HTTP action destination by calling the `CreateTopicRuleDestination` operation or by using the AWS IoT console.
After you create a destination, AWS IoT sends a confirmation request to the confirmation URL. The confirmation request has the following format:
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
The content of the confirmation request includes the following information:
arn
The Amazon Resource Name (ARN) for the HTTP action destination to confirm.
confirmationToken
The confirmation token sent by AWS IoT Core. The token in the example is truncated. Your token will be longer. You'll need this token to confirm your destination with AWS IoT Core.
enableUrl
The URL to which you browse to confirm a topic rule destination.
messageType
The type of message.
### Confirming HTTP action destinations
To complete the endpoint confirmation process, if you're using the AWS CLI, you must perform the following steps after your confirmation URL receives the confirmation request.
1.
**Confirm that the destination is ready to receive messages**
To confirm that the HTTP action destination is ready to receive IoT messages, either call the `enableUrl` in the confirmation request, or perform the `ConfirmTopicRuleDestination` API operation and pass the `confirmationToken` from the confirmation request.
1.
**Set topic rule status to enabled**
After you've confirmed that the destination can receive messages, you must perform the `UpdateTopicRuleDestination` API operation to set the status of the topic rule to `ENABLED`.
If you're using the AWS IoT console, copy the `confirmationToken` and paste it into the destination's confirmation dialog in the AWS IoT console. You can then enable the topic rule.
### Sending a new confirmation request
To activate a new confirmation message for a destination, call `UpdateTopicRuleDestination` and set the topic rule destination's status to `IN_PROGRESS`.
Repeat the confirmation process after you send a new confirmation request.
### Disabling and deleting an HTTP action destination
To disable a destination, call `UpdateTopicRuleDestination` and set the topic rule destination's status to `DISABLED`. A topic rule in the DISABLED state can be enabled again without the need to send a new confirmation request.
To delete an HTTP action destination, call `DeleteTopicRuleDestination`.
## Certificate Authority Support
**Note**
Self-signed certificates are not supported.
HTTPS Endpoints in an HTTP action destination support certificates issued by both [AWS Private Certificate Authority ](https://www.amazontrust.com/repository/) and [Lets Encrypt](https://letsencrypt.org/certificates/).