Skip to main content

Event triggers

Event Triggers enable you to invoke webhooks when a database event happens. Event Triggers are typically used to do post-processing tasks, using custom backend code, based on database events.

Event Triggers are associated with a specific table in the database and the following event types are available:

  • INSERT - A row is inserted into a table.
  • UPDATE - A row is updated in a table.
  • DELETE - A row is deleted from a table.
info

It's currently only possible to create Event Triggers in the Hasura Console. We're working on adding support for creating Event Triggers in the Nhost Dashboard.

Example Use Case​

Let's say you're building an e-commerce application and you want to send an email to the customer when a new order is placed. Orders are stored in the orders table in your database.

To send out an email every time a new order is placed, you create an event trigger that listens for the INSERT event on the orders table. Now every time an order is placed, the event trigger invokes a webhook with the order information, and the webhook sends out the email.

Create Event Trigger​

Event Triggers are managed in the Hasura Console. Select Events in the main menu and click Create to add an Event Trigger.

Event Triggers and Serverless Functions​

Event Triggers and Serverless Functions are a perfect combination to build powerful database-backend logic. Every Serverless Function is exposed as an HTTP endpoint and can be used as a webhook for Event Triggers.

Format​

When using Serverless Functions as webhooks you should configure the webhook using a combination of environment variables and endpoints like this:

{{NHOST_FUNCTIONS_URL}}/orders-insert-send-email

Webhook URL Format

The NHOST_FUNCTIONS_URL is a system environment variable and available in production and in development environments using the CLI.

Security​

To make sure incoming requests to your webhook comes from Hasura, and not some malicious third party, you can use a shared webhook secret between Hasura and your webhook handler (e.g. your Serverless Function).

It is recommended to use the NHOST_WEBHOOK_SECRET, which is a system environment variable and available in production and in development environments using the CLI. The NHOST_WEBHOOK_SECRET is available both in Hasura and in every Serverless Function.

To set this up is a two-step process:

  • Step 1: Add the header nhost-webhook-secret with the value NHOST_WEBHOOK_SECRET (From env var) when creating the Event Trigger in the Hasura Console.

Webhook Secret Header

  • Step 2: Check the header nhost-webhook-secret for incoming requests and make sure the header is the same as the environment variable NHOST_WEBHOOK_SECRET.

Here is an example of how to check the header in a Serverless Function:

export default async function handler(req, res) {
  // Check header to make sure the request comes from Hasura
  if (req.headers['nhost-webhook-secret'] !== process.env.NHOST_WEBHOOK_SECRET) {
    return res.status(400).send('Incorrect webhook secret')
  }

  // Do something
  // Example:
  // - Send an email
  // - Create a subscription in Stripe
  // - Generate a PDF
  // - Send a message to Slack or Discord
  // - Update some data in the database

  console.log(JSON.stringify(req.body, null, 2))

  return res.send('OK')
}

The NHOST_WEBHOOK_SECRET is a system environment variable and available in production and in development environments using the CLI.

Next Steps​