Introducing Actions: Custom GraphQL mutations driven by eventing

Hasura makes it easy to integrate business logic into your GraphQL API with an eventing system called Actions.


How you set it up

  1. Build an event handler (an API, a serverless function, a Postgres function)
  2. Attach a mutation spec and optionally configure relationships to connect the output of the event handler to the rest of the "graph", that Hasura will enrich automatically
An event handler (eg. REST API) that backs a GraphQL mutation

How it works

1) GraphQL mutation → Event

Hasura receives the GraphQL mutation and converts this request into an event payload.

Mutation to Event

2) Event captured → Persisted → Event delivered

The event is captured, persisted and then delivered to the handler with the appropriate retry/delivery guarantees. The event handler can be an API endpoint, a serverless function or even a Postgres function!

Event captured and delivered to handler

3) Event handler runs → Event response

The event handler runs and returns a response that is captured as an event and again persisted to the event store.

The handler response is then put back the event store

4a) Sync mode: Event response → Enrich → GraphQL mutation response

In "sync" mode, the GraphQL client is not aware of the event driven flow and gets the appropriate response within the GraphQL mutation response fields.

Sync mode: Get the results of the event handler in the GraphQL mutation response fields

4b) Async mode: Event response → Enrich → GraphQL subscription

In "async" mode, the GraphQL client can subscribe to the results of the action, and get an updated result when the event response is available!

Async mode: Subscribe to the result of the event handler with a GraphQL subscription

End-to-end GraphQL architecture with Actions

We thought about Actions inspired from a one-way data flow architecture.  In this pattern, the "write models" are separate from "read models". Instead of CRUD on resources, an architecture leveraging actions would be more similar to CQRS or to a redux like flow! More details about how this relates to other architectures in the next section.

This is what an end to end GraphQL architecture using Hasura Actions would look like:

An end-to-end GraphQL architecture with Actions

Use-cases & Benefits

Actions in Hasura bring several benefits to your backend workflow:

  1. Build event-driven backends without the operational and setup effort
  2. Event handlers can be completely independent (microservices, serverless functions) and need not care about GraphQL types, schemas and relationships
  3. API consumers get convenient GraphQL mutations which can reference the entire graph
  4. Switch between sync & async modes depending on what is best for the API consumer without burdening the authors of the event handler

An architecture with Actions that drive business logic is very similar to the CQRS and the 3factor architecture pattern.

Image from


We've built a simple food ordering app that uses a Actions to create and end-to-end async workflow. Actions fits into the 3factor architecture as the eventing plumbing to drive business logic easily!

Try it out!

Actions is available in v1.2.0 (currently in beta). Try it out via the instructions here and get your questions answered on the Hasura discord!

Hasura is an open-source engine that gives you realtime GraphQL APIs on new or existing Postgres databases, with built-in support for stitching custom GraphQL APIs and triggering webhooks on database changes.

PS: We’re hiring!

Tanmai Gopal

Tanmai Gopal

Tanmai is the co-founder of He is passionate about making it easier to build things.

Read More