Outbound HTTP requests
An HttpRequest is an asynchronous outbound HTTP call, available as an action type in both triggers and processors. These actions are queued during trigger or processor execution and dispatched after the response is sent to the client. They are fire-and-forget — they do not block the response.
Quick example
Send a webhook notification when content under /blog/ is created or updated:
<div itemscope itemtype="https://pagelove.org/Trigger">
<meta itemprop="resource" content="/blog/*">
<meta itemprop="method" content="PUT">
<meta itemprop="method" content="POST">
<div itemprop="action" itemscope itemtype="https://pagelove.org/HttpRequest">
<meta itemprop="url" content="https://hooks.example.com/notify">
<meta itemprop="method" content="POST">
<meta itemprop="body" content="Blog content updated">
</div>
</div>
Properties
url (required)
Target URL for the outbound request.
<meta itemprop="url" content="https://hooks.example.com/notify">
The target must be a public address. A request to an internal address is
refused, so you cannot reach loopback, a private network, a link-local address
or a cloud metadata endpoint. The check uses the IP addresses a host name
resolves to when the connection is made. Internal ones the operator has not
allowed are never used: the request goes only to the other addresses, and is
refused when the name has none.
Every redirect is checked the same way. (A transition handler
follows no redirects: a 3xx answer is a failed attempt.) A refused request fails like any
other failed outbound request. It is not retried, and the reason appears in the
server's log. An operator can allow named internal addresses for a deployment
that needs them.
method
HTTP method. Defaults to POST. Supported methods: GET, POST, PUT, DELETE, PATCH.
<meta itemprop="method" content="POST">
content-type
Content-Type header sent with the request. Defaults to text/html.
<meta itemprop="content-type" content="application/json">
body
Request body content.
<meta itemprop="body" content="<p>Content was updated</p>">
header
An additional request header, written as a Pair of key and value. Repeat
the property for as many headers as the request needs — this is how an outbound
request carries an API token, a tenant identifier, or anything else the service
you are calling expects.
<div itemprop="action" itemscope itemtype="https://pagelove.org/HttpRequest">
<meta itemprop="url" content="https://api.postmarkapp.com/email">
<meta itemprop="content-type" content="application/json">
<div itemprop="header" itemscope itemtype="https://pagelove.org/Pair">
<meta itemprop="key" content="X-Postmark-Server-Token">
<meta itemprop="value" content="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d">
</div>
<div itemprop="header" itemscope itemtype="https://pagelove.org/Pair">
<meta itemprop="key" content="Accept">
<meta itemprop="value" content="application/json">
</div>
</div>
A header value can be dynamic, like any other property:
<div itemprop="header" itemscope itemtype="https://pagelove.org/Pair">
<meta itemprop="key" content="X-Request-Path">
<div itemprop="value" itemscope itemtype="https://pagelove.org/Sessel">
<script itemprop="source" type="text/sessel">
@schema Context url("https://pagelove.org/Context");
Context.request.path
</script>
</div>
</div>
A header may also be written as a single line of text, split on its first colon:
<meta itemprop="header" content="X-Api-Version: 2">
Repeats are kept. The same field name may appear more than once, and headers are sent in the order you write them.
Content-Type has one home. If a header sets Content-Type, it replaces
the content-type property rather than being sent alongside it, so the field
never appears twice. A transition handler
is the exception: its delivery is always text/html, so a Content-Type
header on it is dropped.
Malformed headers are dropped. A name that is not a valid HTTP field name, or a value containing control characters such as carriage return or line feed, is discarded rather than sent — including when a dynamic value produces one. The rest of the request is unaffected.
A header value written here lives in the document. An API token in a
headeris stored in the document that declares it, and is readable by anyone your authorization rules allow to read that document. Keep documents that carry credentials off any path that grants public read access.
Static vs dynamic properties
Any property can be either a static literal or a dynamic Sessel or JavaScript expression. This makes it possible to build request URLs and bodies from request context:
<div itemprop="action" itemscope itemtype="https://pagelove.org/HttpRequest">
<!-- Static method -->
<meta itemprop="method" content="POST">
<!-- Dynamic URL built from request path (Sessel) -->
<div itemprop="url" itemscope itemtype="https://pagelove.org/Sessel">
<script itemprop="source" type="text/sessel">
@schema Context url("https://pagelove.org/Context");
"https://hooks.example.com/" + Context.request.path
</script>
</div>
<!-- Dynamic body built from request data (Sessel) -->
<div itemprop="body" itemscope itemtype="https://pagelove.org/Sessel">
<script itemprop="source" type="text/sessel">
@schema Context url("https://pagelove.org/Context");
Context.request.path
</script>
</div>
</div>
The same properties accept a https://pagelove.org/JavaScript/Module typed item instead. The language is selected per property by its itemtype, so a single HttpRequest action can mix Sessel and JavaScript across different properties:
<div itemprop="action" itemscope itemtype="https://pagelove.org/HttpRequest">
<!-- Dynamic URL built from request path (JavaScript) -->
<div itemprop="url" itemscope itemtype="https://pagelove.org/JavaScript/Module">
<script type="module" itemprop="source">
export default function(ctx) { return "/api/" + ctx.request.path; }
</script>
</div>
<meta itemprop="method" content="GET">
</div>
Retry
Requests are not retried unless you ask. retry defaults to 0, meaning the request is
attempted once and abandoned if it fails:
<meta itemprop="retry" content="3">
That asks for 3 retries — at most 4 attempts in total. Error handling lists the failures that are not retried. Retries use exponential backoff:
| Attempt | Delay before attempt |
|---|---|
| 1 | immediate |
| 2 | 2 seconds |
| 3 | 4 seconds |
| 4 | 8 seconds |
| 5 | 16 seconds |
The maximum useful value of retry is 4, which gives at most 5 attempts in total. A larger number is
not an error — it is clamped to 4 — so retry of 9 behaves exactly as 4. The backoff delay
would be capped at 30 seconds, though the schedule above never reaches that cap. After the
attempts are exhausted, the request is abandoned.
retry is a plain number: unlike url, body and header values, it cannot be a Sessel or
JavaScript expression.
Failures do not affect the client response (already sent).
Error handling
This section describes triggers and processors. A transition handler
sends its request from a stored queue instead. It makes up to 36 attempts with growing delay and
then parks the notification, whatever retry says, and it follows no redirects.
- Transport errors (connection refused, timeout): retried according to the retry schedule —
or, with the default
retryof 0, not retried at all. A request waits at most 10 seconds to connect and 30 seconds in all, from the start of the connection to the end of the response. A request that goes over either limit counts as a transport error. You cannot change these limits. - Non-2xx responses: same — retried only as far as
retryasks. The exception is a500or503response that says the request's save was stored. That request did its write and only the response failed, so it is not retried, because a retry would store the save again. A notice counts when the exact textitemprop="https://pagelove.org/saveStored" value="true"is within the first 64 KiB of the body and is read within 5 seconds of the response headers arriving and within the request's 30 second limit. A body of any length counts when the notice is found in time. Otherwise the request is retried. Pagelove reads the body only when a retry could follow. A body that only mentions the property name does not count. - An unsupported method: fails at once and is not retried. The supported methods are
GET,POST,PUT,DELETEandPATCH. - A request that cannot be built: fails at once and is not retried, because every attempt
would fail the same way. This covers a URL that does not parse or is not
httporhttps, and a header name or value that is not valid. - A redirect Pagelove could not follow: fails at once and is not retried. This covers a
redirect to a URL that is not
httporhttps, and a redirect to a target that is not a valid URL, such ashttp://example.com:99999/. The server you called chose that target, so a later attempt might not fail the same way. Pagelove chooses not to retry. A redirect whoseLocationheader cannot be read at all is not followed, and its3xxresponse counts as a failed attempt, retried as far asretryasks. - A target at an internal address: refused at once and not retried. This covers a host name
whose addresses are all internal, and a redirect to an internal address. See
url. - After the attempts are exhausted: the request is abandoned. No effect on the client.
See also
- Triggers — fire before core processing
- Processors — fire after core processing
- JavaScript in schemas — JavaScript as a Pagelove binding language
- Sessel language reference — expression language for dynamic properties