Creating an API Call Notification

This guide will help you create an API Call Notification that pings an API endpoint when a new user signs up.

Requirements

To follow the steps in this tutorial, you should understand the concept of notifications. You'll also use the sign-up form you created in a previous tutorial.

• Form Configuration
• Notifications
• Creating a Sign Up Form

Steps

Creating an API Call Notification is a two-step process:

Step 1: Create API Call Notification

app/api_calls/ping_example_com_on_user_sign_up.liquid

---
to: 'https://example.com/endpoint/{{ form.id }}'
format: http
callback: >
  {% log response, type: 'response object' %}
  {% assign response_hash = response.body | parse_json %}
  {% log response_hash, type: 'response body as hash' %}
request_type: POST
request_headers: '{
  "Content-Type": "application/json"
}'
---
{
  "first_name": "{{ form.first_name }}",
  "id": "{{ form.id }}"
}

This defines a POST request to the endpoint with the newly created user's ID. In this example the body of the request is JSON, and to notify the endpoint about it, you set the Content-Type header to application/json. If the call is successful, then the code from the callback property is triggered. You can access the endpoint's response via the Response object - which includes headers, status and body. In the example, we assume the server returns valid JSON, which we parse and log.

Step 2a: Invoke notification directly via GraphQL api_call_send

The API Call notification name is a path of the file relative to the api_calls directory, without extension.

For app/api_calls/ping_example_com_on_user_sign_up.liquid - the bolded part is the name (physical_file_path).

To easily test your newly created API Call Notification you can trigger it using the following query:

mutation send_api_call ($data: HashObject) {
  api_call_send(
    data: $data
    template: { name: "ping_example_com_on_user_sign_up" }
  ) {
    response {
      status
      body
    }
    errors {
      message
    }
  }
}

All parameters provided via GraphQL as data argument, will be accessible in every API Call Notification property as a data variable (or form to make it compatible with Form).

This is how you can prepare the data HashObject for this mutation:

{% parse_json data %}
{
  "first_name": "Michael",
  "id": "0386676"
}
{% endparse_json %}

{% graphql notify = 'api_calls/ping_example_com_on_user_sign_up', data: data %}

Step 2b: Connect notification to sign up form

Connect the API Call Notification you created with the sign up form forms/developer/sign_up.liquid:

api_call_notifications:
  - ping_example_com_on_user_sign_up

Whenever a user successfully signs up, the https://example.com/endpoint/{{ form.id }} endpoint will be notified.

Next steps

Congratulations! You have created an API Call Notification. Now you can learn about parsing an API response.

• Parsing an API Response