What an API's api: block and a webhook's webhook: block share: where the request goes, how it
authenticates and signs, which answers count, and how it travels. Each block adds its own (a
webhook's body, an API's per-file flow); these settings work the same in both.
url: https://api.example.com/users/$file.stem # templated
method: PUT # an API's default PUT, a webhook's POST
headers: {X-Team: ops} # templated; never a secret
query: {dryRun: "false"} # templated, encoded, added to the URL
auth: bearer # see below
signature: {} # see below
success_status: [200-299] # default: any 2xx
retry_on_status: [429, 500-599] # the default
follow_redirects: false # the default
tls:
ca_file: /etc/ssl/internal-ca.pem
client_credential: cred-mtls
insecure_skip_verify: false
proxy: http://proxy.example.com:3128 # or none; left out: HTTPS_PROXY / NO_PROXY
rate_limit: {requests: 10, per_seconds: 1}The item around the block adds credential (whose fields auth and signature read),
timeout_seconds (one attempt, at most 300) and retry.
One word, or a mapping with a type. Left out: a bearer token when the item's credential has a
token, nothing otherwise.
auth |
Sends | Reads from the credential |
|---|---|---|
none |
Nothing | — |
bearer |
Authorization: Bearer <token> |
token |
basic |
Authorization: Basic … |
username, password (may be empty) |
{type: header, name: X-API-Key} |
The token in that header | token |
{type: query, name: api_key} |
The token as that query parameter | token |
{type: oauth2, …} |
Authorization: Bearer <access token> |
client_id, client_secret |
{type: login, …} |
The token a login call answered | whatever its body names |
OAuth 2.0 client credentials, kept until shortly before it expires:
auth:
type: oauth2
token_url: https://idp.example.com/oauth2/token
scopes: [read, write]
audience: https://api.example.com # optional
client_auth: basic # basic (default) | bodyA login call first, for APIs that hand out a session token:
auth:
type: login
url: https://portainer.example.com/api/auth
method: POST # default POST
body: {Username: $credential.username, Password: $credential.password}
token: $response.jwt # or $headers.x-auth-token
header: Authorization # default Authorization
prefix: "Bearer " # default "Bearer "
ttl_seconds: 300 # reuse it this long (default 300)A bought token (oauth2, login) that the API answers with a 401 is bought again, and the request sent again once.
An HMAC of what is sent, for receivers that check signatures:
signature:
credential: cred-signing # default: the item's credential
field: secret # default secret
algorithm: sha256 # sha256 (default) | sha512
encoding: hex # hex (default) | base64
header: X-Hub-Signature-256 # the default
prefix: "sha256=" # default by algorithm
timestamp_header: X-Timestamp # optional: sign "<unix seconds>.<body>", send the secondssuccess_statusandretry_on_statustake numbers, ranges ("200-299") and classes (2xx). An answer in neither is final.retryis the item's:attemptsin all, the first included (default 4; a script's default is 1), waitinginitial_delay_seconds(1), doubling (backoff: exponential) or not (fixed), at mostmax_delay_seconds(60). ARetry-Afterin seconds is honoured, within that bound.- No answer at all (refused, timed out, TLS) is retried too; a request that cannot be built (a credential without the field auth reads, a value with a line break) is not.
tls.ca_filetrusts that PEM bundle instead of the system's CAs;tls.client_credentialnames a credential whosecertandkeyfields hold a client certificate and its key, in PEM, for mutual TLS;insecure_skip_verifyaccepts any certificate (a lab; refused besideca_file).proxyis anhttp://,https://orsocks5://URL, ornoneto bypass the environment's.follow_redirectsis off: a redirect would resend the body, credentials included, wherever the receiver points.rate_limitspaces every request the item sends (retries and polls included) across all its runs.
url, headers, query and a body are templates: $event.<field>, and for an API $file and
$doc. ${event.project} ends a name where text follows, $$ writes a $, and a $ that starts
no name ($5) is text. Every template is checked when the configuration loads.