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