GraphcoolDocs
FAQ

Subscriptions

Last updated a day ago Edit this page

Subscriptions are a simple yet powerful event-based concept on top of GraphQL to implement business logic asynchronously.

#Overview

Subscriptions are a simple yet powerful concept to handle business logic in your service. You can subscribe to specific events that are happening inside the GraphQL engine. All (successful) mutations are considered events.

Unlike hooks, functions for subscriptions are called asynchronously, after a database transaction was entirely processed.

#Input type

The input data for subscription functions is determined by the subscription query that you write for the subscription.

The concrete shape of the subscription query is determined by the Subscription API.

#Adding a Subscription function to the service

When you want to create a subscription function in your Graphcool service, you need to add it to the service configuration file under the functions section.

#Example

Here is an example of a subscription function:

1
2
3
4
5
6
functions:
  sendWelcomeEmail:
    type: subscription
    query: newUser.graphql
    handler:
      webhook: http://example.org/welcome-email

This is what the referred newUser.graphql contains:

1
2
3
4
5
6
7
8
9
10
11
subscription {
  User(filter: {
    mutation_in: [CREATED]
  }) {
    node {
      id
      email
      name
    }
  }
}

sendWelcomeEmail is invoked after a User node was created and is defined as a webhook. It receives as input the payload of the subscription query that's defined in newUser.graphql, i.e. the new user's id, name and email.

#Properties

Each function that's specified in the service configuration file needs to have the type and handler properties.

For subscription functions, you additionally need to specify the query property which points to a file containing a regular GraphQL subscription query.

#Example

Calling out to 3rd-party APIs

Send an email when a new customer is created

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const fetch = require('isomorphic-fetch')
const Base64 = require('Base64')
const FormData =require('form-data')

const apiKey = '__MAILGUN_API_KEY__'
const url = '__MAILGUN_URL__'

export default event => {

  const form = new FormData()
  form.append('from', 'Nilan <nilan@graph.cool>')
  form.append('to', 'Nikolas <nikolas@graph.cool>')
  form.append('subject', 'Test')
  form.append('text', 'Hi')

  return fetch(url, {
    headers: {
      'Authorization': `Basic ${Base64.btoa(apiKey)}`
    },
    method: 'POST',
    body: form
  })
}

#Current limitations

Currently, no Subscriptions are triggered for the File type.

Was this page helpful?