Webhook Configuration
Basics
This section describes the webhook configuration options available in RelyAuth.
Payload Definition
Example webhook payload configuration definition:
version: v1
kind: RelyAuth
definition:
modes:
- mode: webhook
url:
env: AUTH_WEBHOOK_URL
method: POST
customRequest:
headers:
forward:
- Authorization
additional:
user-agent:
default:
value: "RelyChan"
body:
type: gotmpl
contentType: application/json
template: |
{
"access_token": "{{ index .headers "content-type" }}"
}
customResponse:
response:
type: jmespath
template:
type: object
properties:
x-hasura-role:
type: field
path: body.role
x-hasura-user-id:
type: field
path: body.userId
GET vs POST
For a GET request, the headers received by the RelyAuth engine on the query can be forwarded to the webhook as actual headers on the request and the body will be empty. The following headers will be replaced by the engine's HTTP client even if you specify them in the forwarded headers setting:
Accept
Accept-Datetime
Accept-Encoding
Accept-Language
Cache-Control
Connection
Content-Length
Content-MD5
Content-Type
DNT
Host
Origin
Referer
User-Agent
For a POST request, the headers received by the RelyAuth engine on the query can be forwarded to the webhook in a JSON
object in the body of the request under a headers key. The body of the POST request can have more details than the GET
method such as request URL and the request body of the raw request. Original headers aren't be ignored in the POST
request.
For the sample configuration above, the webhook will receive the Authorization and Content-Type headers in the body
of the request:
{
"headers": {
"Authorization": "Bearer some-token",
"Content-Type": "application/json"
}
}
Also, the webhook will receive the user-agent header as an actual header on the request.
You can use environment variables to dynamically and securely add the webhook URL to your configuration. Alternatively,
you can include raw strings here using value instead of env.
Custom Request
Request Template Variables
First, let's look at the structure of request variables that you can use in custom templates:
type RequestVariables = {
url: string;
headers: Record<string, string>;
body?: unknown;
};
url: URL of the original request.headers: a string map of request headers. Object keys are lower case.bodyis only present in the POST method and if the request have a body. It should be in the JSON format.
Transform Custom Headers
You can inject custom headers to every requests with the additional object. For each property, you can:
- set a literal value.
- or select fields from the request using JMESPath.
For example, this example rejects the user-agent: RelyChan to every request.
mode: webhook
url:
env: AUTH_WEBHOOK_URL
method: GET
customRequest:
headers:
additional:
user-agent:
default:
value: "RelyChan"
This example picks the environment from request headers, and fallback to dev:
mode: webhook
url:
env: AUTH_WEBHOOK_URL
method: GET
customRequest:
headers:
additional:
environment:
default:
value: dev
path: 'headers."x-request-env"'
Transform Custom Body
The body is present only if the request method is POST. It will be ignored in the GET method.
RelyAuth supports the following templates:
jmespath: a structured, recursive type using JMESPath.gotmpl: use Go template string.
In this example, we use gotmpl to transform a JSON object body with access token that is selected from the
Authorization header.
mode: webhook
url:
env: AUTH_WEBHOOK_URL
method: POST
customRequest:
body:
type: gotmpl
contentType: application/json
template: |
{
"access_token": "{{ .headers.authorization }}"
}
This example transforms to the same JSON object using the jmespath template.
mode: webhook
url:
env: AUTH_WEBHOOK_URL
method: POST
customRequest:
body:
type: jmespath
template:
type: object
properties:
access_token:
type: field
path: headers.authorization
The structure of JMESPath template is safer than Go template for JSON format. In Go template, you need to validate the JSON syntax of the rendered output carefully, or it will break your runtime.
Forward Headers
Headers are forwarded to the auth webhook from the client on each request received by the API gateway either as headers
for a GET request or as a JSON object in the body of a POST request under a headers key.
You can configure the headers that are sent to the webhook in the optional customRequest field. If the field is not
provided, the default behavior is to forward all headers (after filtering out commonly used headers - GET method only)
received by the API gateway on the query to the webhook.
When using customRequest, you can explicitly forward any headers, including those that are ignored by default. This
gives you full control over which headers are sent to the webhook.
It is recommended to use the customRequest field to configure only the headers that are required by the webhook and
not forward any other headers. This will help in reducing the size of the request and improve the performance of the
webhook.
In this example, we're passing the access token in the Authorization header, however webhook mode is flexible and you
can pass any headers you wish.
If you want to forward all headers received by the engine on the query to the webhook, you can set forward: "*". This
will forward all headers received by the engine on the query to the webhook, excluding the ignored headers.
Token Parsing
In this example, the webhook is then responsible for validating and parsing the token passed in the header. It will need to:
-
Extract the Token: Retrieve the Authorization header from the incoming request and extract the token.
-
Validate the Token: Use a library or your own logic to validate the token. This involves verifying the token's signature with the secret key.
-
Extract Claims: Decode the token to extract the claims.
Response
Specifications
Based on the validation result, the webhook will need to respond with either a 200 status code (for a valid token) or
a 401 status code (for an invalid or missing token).
You should respond with session variables in an object in the body of your response. The value of each session variable can be any JSON value.
HTTP/1.1 200 OK
Content-Type: application/json
{
"X-Rely-Role": "user",
"X-Rely-User-Id": 25
}
Transform Response
If you can't modify the response body to satisfy the specification, you can configure customResponse setting in the
webhook configuration.
Response Template Variables
The structure of response variables is similar to the request variables object excepts the request url:
type ResponseVariables = {
headers: Record<string, string>;
body?: unknown;
};
headers: a string map of response headers. Object keys are lower case.body: response body of the remote webhook service that should be in the JSON format.
Custom Response Body
In this example, the original response has the following body:
{
"role": "user",
"userId": "1"
}
We need to configure the customResponse to return the Hasura-compliant session variables format with a role and user
ID.
version: v1
kind: RelyAuth
definition:
modes:
- mode: webhook
url:
env: AUTH_WEBHOOK_URL
customResponse:
response:
type: jmespath
template:
type: object
properties:
x-hasura-role:
type: field
path: body.role
x-hasura-user-id:
type: field
path: body.userId
The transformed output will be:
{
"x-hasura-role": "user",
"x-hasura-user-id": "1"
}