Skip to main content
Version: v2.x

REST Connectors for event triggers


REST Connectors for event triggers are used to invoke existing or third-party webhooks without needing any middleware or modifications to the upstream code.

REST Connectors modify the event trigger's HTTP request to adapt to your webhook's expected format by adding suitable transforms.

Supported from

REST Connectors are supported in Hasura GraphQL Engine versions v2.1.0 and above.

Configuring REST Connectors

REST Connectors can be configured either when creating a new event trigger or editing an existing one. See the transform options here:

Go to the Events tab on the console and create or modify an event trigger. Scroll down to Configure REST Connectors section:

Configure REST Connectors for event triggers

Context Variables

You can use context variables in the transforms to achieve dynamic behavior for each request.

The context variables available in transforms are:

Context variableValue
$bodyOriginal body of event request
$base_urlOriginal configured webhook URL
$session_variablesSession variables
$query_paramsQuery parameters and the values to be sent to the webhook

Console sample context

The console allows you to preview your transforms while configuring them. To avoid exposing sensitive information on the console UI the actual environment variables configured on the server are not resolved while displaying the previews. Also any session variables used in the transform will not be available at the time of configuration.

Hence, the console allows you to provide mock env variables and session variables to verify your transforms. If you configure your transforms without providing the mock env/session variables you might see a UI validation error in the preview sections.

For example: If your webhook handler is set as an env var as shown below then pass a mock value for that env var in the sample context:

Console event trigger webhook handler

You can enter the mock env/session variables under Configure REST Connectors > Sample Context:

Add generic sample context

As the sample context is only used for previews, you can still configure the transforms on the console without setting any sample context.

Types of transforms

REST Connectors allow you to add different transforms to the default HTTP request. You can also use context variables in the transforms to achieve dynamic behavior for each request.

You can transform your:

Request Method

You can change the request method to adapt to your API's expected format.

Head to the Events > [event_trigger_name] page. Under Configure REST Connectors click on Add Request Options Transform.

Select the Request Method.

Change request method

Hit Save Event Trigger to apply your changes.

Request URL

The Request URL template allows you to configure the exact API endpoint to call.

You can use the context variables to construct the final URL.

You can also provide query params to add to the URL.

You can use the Kriti templating language to construct any string values here.

Head to the Events > [event_trigger_name] page. Under Configure REST Connectors click on Add Request Options Transform.

Enter the Request URL Template and Query Params.

Console event trigger request options transformation

The value of the final url should be reflected in the Preview section given all required sample context is set.

Hit Save Event Trigger to apply your changes.


Use the escapeUri function to urlencode templated values. For example, if you have to use session variables in the URL and those may contain non-ASCII values, then you should provide the template URL as {{$base_url}}/{{escapeUri $session_variables['x-hasura-user-id']}}.

Request Content-Type

You can change the Content-Type of the request to either application/json or x-www-form-urlencoded. The default is application/json.

Console support coming soon.

With x-www-form-urlencoded, the key-value pairs in body are transformed to name={{$}}&key2={{$}}.

Request Body

You can generate a custom request body by configuring a template to transform the default payload to a custom payload. The body field takes a template in the Kriti templating language to evaluate the transform.

For example, you can obtain the following transformed event trigger request body for a users table:

Transformed Request Body

Head to Events > [event_trigger_name] > Modify tab. Under Configure REST Connectors click on Add Payload Transform.

A sample payload input auto-generated based on your schema is shown.

Under Configure Request Body enter the required request body template:

Configure request body

The transformed sample payload should be shown as the Transformed Request Body given all required sample context is set.

Hit Save Event Trigger to apply your changes.

Example: Trigger SendGrid's Mail Send API

To see the REST Connectors for event triggers in action, let's set up an event trigger to send an email using the SendGrid Mail Send API.

Let's say you have a table users (id int, name text, email text) and you would like to send the user an email whenever a new user is inserted into the users table.

Step 1: Configure event trigger details

Head to the Events tab on your console and create a new event trigger.

The SendGrid Mail Send API is available at POST and expects an Authorization header to be passed with a SendGrid API key for access (see docs).

You can configure env vars, say SENDGRID_BASE_URL with the value and SENDGRID_API_KEY with the value Bearer <sendgrid-api-key> on the server so that they can be used for this event trigger and any other SendGrid requests we might want to use in the future.

You can now configure the event trigger as follows:

Table: users

Operations: Insert


Headers: Authorization: SENDGRID_API_KEY

Sengrid event trigger config

Step 2: Configure REST connector

Step 2.1: Add Sample Context

Set a mock value for the SENDGRID_BASE_URL env var to verify your URL transform that we will be configuring next as the actual value is not exposed to the console.

Sengrid event trigger context

Step 2.2: Add Request Transforms

Request Method and URL template

The SendGrid API request uses the POST request method so you can choose that.

We need to add /v3/mail/send to the SendGrid base URL ( that we configured in the env var. This can be done by setting the URL template as {{$base_url}}/v3/mail/send.

Sengrid event trigger request options
Request Body

Here is the request body template we would need for the SendGrid Mail Send API (see docs).

We replace the email and name values from the event trigger body:

"from": { "email": "<from_email>", "name": "<from_name>" },
"email": {{ $ }},
"name": {{ $ }}
"from": { "email": "<from_email>", "name": "<from_name>" },
"reply_to": { "email": "<replyto_email>", "name": "<from_name>" },
"subject": "Welcome!",
"type": "text/html",
"value": "<p>Mail from a Hasura event trigger!</p>"
Sengrid event trigger payload

Hit Create Event Trigger to complete the event trigger set up.

Step 3: Test the event trigger

Insert a new user to the users table to call the SendGrid API.

Navigate to Data > [database-name] > public > users and insert a new row.

The insert operation triggers the event trigger and sends the transformed request to the SendGrid API which should send an email to the inserted user.

You can view the Processed Events and Invocation Logs for the event trigger to check the SendGrid API response.

Event trigger logs

Explore the Hasura Data Hub source code for Event Connectors with different platform integrations.