ContextQMD
Back to Graphql Engine

Create an Event Trigger

docs/docs/event-triggers/create-trigger.mdx

2.49.512.1 KB
Original Source

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Thumbnail from '@site/src/components/Thumbnail';

Create an Event Trigger

Introduction

Event Triggers can be created using the Hasura Console, Hasura CLI, or Metadata APIs. Currently, support for event triggers exists for Postgres and MSSQL databases.

:::info Note

  • Event Triggers are supported for Postgres and MS SQL Server databases.
  • Event webhook notifications will be delivered at least once, and may arrive out of order with respect to the underlying event.

:::

:::caution Caveat on different Hasura instances connected to the same database

Event Triggers store their data in the underlying database and hence different instances acting on the same data can cause undefined behavior during run-time. This should not be a problem if the Hasura instances have the same metadata.

:::

Creating triggers

<Tabs groupId="user-preference" className="api-tabs"> <TabItem value="console" label="Console">

Open the Hasura Console, head to the Events tab and click on the Create button to open the page below:

<Thumbnail src="/img/event-triggers/create-event-trigger.png" alt="Create an Event Trigger" /> </TabItem> <TabItem value="cli" label="CLI">

You can add an Event Trigger for a table by updating the databases > [source-name] > tables > [table-name].yaml file inside the metadata directory:

yaml
- table:
   schema: public
   name: author
event_triggers:
   - name: author_trigger
   definition:
      enable_manual: false
      insert:
         columns: "*"
      update:
         columns: "*"
   webhook: https://httpbin.org/post

Apply the Metadata by running:

bash
hasura metadata apply
</TabItem> <TabItem value="api" label="API">

You can create Event Triggers by using the appropriate Metadata API, either: pg_create_event_trigger or mssql_create_event_trigger.

To create an Event Trigger via the the Metadata API, replace <db_type_create_event_trigger> with the following:

  • Postgres: pg_create_event_trigger
  • MSSQL: mssql_create_event_trigger
http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type" : "<db_type_create_event_trigger>",
   "args" : {
      "name": "author_trigger",
      "source": "<db_name>",
      "table": {
         "name": "author",
         "schema": "public"
      },
      "webhook": "https://httpbin.org/post",
      "insert": {
            "columns": "*"
      },
      "update": {
            "columns": "*"
      }
   }
}
</TabItem> </Tabs>

:::info Note

UPDATE Event Trigger for MSSQL will only work on tables that have a primary key.

:::

Parameters

Trigger Name

Unique name for Event Trigger.

Schema/Table

The postgres schema and table name on which the Event Trigger needs to be created.

Trigger Operations

The table operation on which the Event Trigger will be invoked.

Webhook URL

The HTTP(s) URL which will be called with the event payload on configured operation. Must be a POST handler. This URL can be entered manually or can be picked up from an environment variable (the environment variable needs to be set before using it for this configuration).

:::info Note

If you are running Hasura using Docker, ensure that the Hasura Docker container can reach the webhook. See this page for Docker networking.

:::

Advanced Settings

Listen columns for update

Update operations are special because you may want to trigger a webhook only if specific columns have changed in a row. Choose the columns here which you want the update operation to listen to.

If a column is not selected here, then an update to that column will not trigger the webhook.

<Tabs groupId="user-preference" className="api-tabs"> <TabItem value="console" label="Console">

Expand the Advanced Settings section on the Hasura Console to define advanced settings for an Event Trigger:

<Thumbnail src="/img/event-triggers/create-event-trigger-listen-columns.png" alt="Listen columns for update Event Triggers" />

</TabItem> <TabItem value="cli" label="CLI">

You can configure advanced settings for Event Triggers in the tables.yaml file inside the metadata directory:

yaml
- table:
    schema: public
    name: author
  event_triggers:
    - name: author_trigger
      definition:
        enable_manual: false
        insert:
          columns: '*'
        update:
          columns:
            - name
            - addr
      webhook: https://httpbin.org/post

Apply the Metadata by running:

bash
hasura metadata apply
</TabItem> <TabItem value="api" label="API">

You can configure advanced settings via the appropriate Metadata API using either pg_create_event_trigger or mssql_create_event_trigger.

Replace <db_type_create_event_trigger> with the following:

  • Postgres: pg_create_event_trigger
  • MSSQL: mssql_create_event_trigger
http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type" : "<db_type_create_event_trigger>",
   "args": {
      "name": "author_trigger",
      "source": "<db_name>",
      "table": {
         "name": "author",
         "schema": "public"
      },
      "webhook": "https://httpbin.org/post",
      "insert": {
         "columns": "*"
      },
      "update": {
         "columns": ["name", "addr"]
      },
      "retry_conf": {
         "num_retries": 0,
         "interval_sec": 10,
         "timeout_sec": 60
      },
      "headers": [
         {
            "name": "X-Hasura-From-Val",
            "value": "static-value"
         },
         {
            "name": "X-Hasura-From-Env",
            "value_from_env": "EVENT_WEBHOOK_HEADER"
         }
      ],
      "replace": false
   }
}
</TabItem> </Tabs>

Retry Logic

Retry configuration is available in the "Advanced settings" when you create a trigger.

  1. num_retries: Number of times a failed invocation is retried. Default value is 0.
  2. interval_sec: Number of seconds after which a failed invocation is retried. Default value is 10.
  3. timeout_sec: Number of seconds before which client closes the connection to the webhook. Default value is 60.
<Tabs groupId="user-preference" className="api-tabs"> <TabItem value="console" label="Console">

Expand the Advanced Settings section on the Hasura Console to define advanced settings for an Event Trigger:

<Thumbnail src="/img/event-triggers/create-event-trigger-retry.png" alt="Retry settings for Event Triggers" /> </TabItem> <TabItem value="cli" label="CLI">

You can configure advanced settings for Event Triggers in the tables.yaml file inside the metadata directory:

yaml
- table:
   schema: public
   name: author
   event_triggers:
   - name: author_trigger
      definition:
         enable_manual: false
         insert:
         columns: '*'
         update:
         columns: ['name']
      retry_conf:
         num_retries: 0
         interval_sec: 10
         timeout_sec: 60
      headers:
      - name: X-Hasura-From-Val
         value: static-value'
      - name: X-Hasura-From-Env
         value_from_env: EVENT_WEBHOOK_HEADER
      webhook: https://httpbin.org/post

Apply the Metadata by running:

bash
hasura metadata apply
</TabItem> <TabItem value="api" label="API">

Again, you can configure advanced settings via the appropriate Metadata API, either: pg_create_event_trigger or mssql_create_event_trigger.

Replace <db_type_create_event_trigger> with the following:

  • Postgres: pg_create_event_trigger
  • MSSQL: mssql_create_event_trigger
http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "<db_type_create_event_trigger>",
   "args": {
      "name": "author_trigger",
      "source": "<db_name>",
      "table": {
         "name": "author",
         "schema": "public"
      },
      "webhook": "https://httpbin.org/post",
      "insert": {
         "columns": "*"
      },
      "update": {
         "columns": ["name"]
      },
      "retry_conf": {
         "num_retries": 0,
         "interval_sec": 10,
         "timeout_sec": 60
      },
      "headers": [
         {
            "name": "X-Hasura-From-Val",
            "value": "static-value"
         },
         {
            "name": "X-Hasura-From-Env",
            "value_from_env": "EVENT_WEBHOOK_HEADER"
         }
      ],
      "replace": false
   }
}

:::info Note

Event Triggers are supported for Postgres and MSSQL databases. To create an Event Trigger via the the Metadata API, replace <db_type> with the following:

  • Postgres: pg
  • MSSQL: mssql

:::

</TabItem> </Tabs>

Headers

Custom headers can be added to an Event Trigger. Each webhook request will have these headers added.

Each header has 3 parameters:

  1. Key: Name of the header e.g. Authorization or X-My-Header.
  2. Type: One of static or from env variable. static means the value provided in the Value field is the raw value of the header. from env variable means the value provided in the Value field is the name of the environment variable in the GraphQL Engine which will be resolved before sending the header.
  3. Value: The value of the header. Either a static value or the name of an environment variable.
<Tabs groupId="user-preference" className="api-tabs"> <TabItem value="console" label="Console">

Expand the Advanced Settings section on the Hasura Console to define advanced settings for an Event Trigger:

<Thumbnail src="/img/event-triggers/create-event-trigger-headers.png" alt="Headers for Event Triggers" /> </TabItem> <TabItem value="cli" label="CLI">

You can configure advanced settings for Event Triggers in the tables.yaml file inside the metadata directory:

yaml
- table:
    schema: public
    name: author
  event_triggers:
    - name: author_trigger
      definition:
        enable_manual: false
        insert:
          columns: '*'
        update:
          columns: ['name']
      retry_conf:
        num_retries: 0
        interval_sec: 10
        timeout_sec: 60
      headers:
        - name: X-Hasura-From-Val
          value: static-value'
        - name: X-Hasura-From-Env
          value_from_env: EVENT_WEBHOOK_HEADER
      webhook: https://httpbin.org/post

Apply the Metadata by running:

bash
hasura metadata apply
</TabItem> <TabItem value="api" label="API">

You can configure advanced settings via the appropriate Metadata API, either: pg_create_event_trigger or mssql_create_event_trigger.

Replace <db_type_create_event_trigger> with the following:

  • Postgres: pg_create_event_trigger
  • MSSQL: mssql_create_event_trigger
http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "<db_type_create_event_trigger>",
   "args": {
      "name": "author_trigger",
      "source": "<db_name>",
      "table": {
         "name": "author",
         "schema": "public"
      },
      "webhook": "https://httpbin.org/post",
      "insert": {
         "columns": "*"
      },
      "update": {
         "columns": ["name"]
      },
      "retry_conf": {
         "num_retries": 0,
         "interval_sec": 10,
         "timeout_sec": 60
      },
      "headers": [
         {
            "name": "X-Hasura-From-Val",
            "value": "static-value"
         },
         {
            "name": "X-Hasura-From-Env",
            "value_from_env": "EVENT_WEBHOOK_HEADER"
         }
      ],
      "replace": false
   }
}
</TabItem> </Tabs>