Authorization using webhooks¶

Table of contents

Spec for the webhook
- Request
- Response

You can configure a webhook (see GraphQL engine server options) to authenticate all incoming requests to the Hasura GraphQL engine server.

Note

Configuring webhook requires Hasura to run with an admin secret (--admin-secret).

The configured webhook is called when X-Hasura-Admin-Secret header is not found in the request.
The configured webhook is ignored when X-Hasura-Admin-Secret header is found in the request.

Spec for the webhook¶

Request¶

You can configure Hasura to send either a GET or a POST request to your auth webhook.

GET request¶

GET https://<your-custom-webhook>/ HTTP/1.1
<Header-Key>: <Header-Value>

If you configure your webhook to use GET, then Hasura will forward all client headers except:

Content-Length
Content-MD5
User-Agent
Host
Origin
Referer
Accept
Accept-Encoding
Accept-Language
Accept-Datetime
Cache-Control
Connection
DNT

POST request¶

POST https://<your-custom-webhook>/ HTTP/1.1
Content-Type: application/json

{
 "headers": {
     "header-key1": "header-value1",
     "header-key2": "header-value2"
   }
}

If you configure your webhook to use POST, then Hasura will send all client headers in payload

Response¶

Success¶

To allow the GraphQL request to go through, your webhook must return a 200 status code. You should send the X-Hasura-* “session variables” to your permission rules in Hasura.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "X-Hasura-User-Id": "25",
    "X-Hasura-Role": "user",
    "X-Hasura-Is-Owner": "true",
    "X-Hasura-Custom": "custom value"
}

Note

All values should be String. They will be converted to the right type automatically.

Failure¶

If you want to deny the GraphQL request return a 401 Unauthorized exception.

HTTP/1.1 401 Unauthorized

Note

Anything other than a 200 or 401 response from webhook makes server raise a 500 Internal Server Error exception.

See:

Auth webhook samples

« previous | next »

Was this page helpful?

Want to contribute or report missing content?

check this page on github | contributing guidelines | report an issue

Hasura GraphQL Engine is open source. See license