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.
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
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 valueNHOST_WEBHOOK_SECRET
(From env var) when creating the Event Trigger in the Hasura Console.
- Step 2: Check the header
nhost-webhook-secret
for incoming requests and make sure the header is the same as the environment variableNHOST_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
- Read the full Event Triggers documentation from Hasura.
- Learn about the GraphQL API.