Creating an API Call Notification

Prerequisites

To follow the steps in this tutorial, you must understand how notifications work and have created a sign-up form as demonstrated in a previous tutorial.

• Form Configuration Options
• Notifications
• Creating a Sign-Up Form

Steps

Creating an API Call Notification and attatching it to a form is a three-step process:

• Step 1: Create an API call notification
• Step 2: Invoke notification directly via GraphQL api_call_send
• Step 3: Connect the notification to the sign-up form

Step 1: Create an 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 request's body is JSON, and to notify the endpoint about it, you set the header to . If the call is successful, the code from the property is triggered. You can access the endpoint's response via the Response object - which includes headers, status and body. In the example, it is assumed that the server returns valid JSON, which is parsed and logged by the system.

Step 2: Invoke notification directly via GraphQL 'api_call_send'

The API Call notification name is a file path relative to the 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 test your newly created API Call Notification, 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
    }
  }
}

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

Save the mutation above as . Then prepare the HashObject and run the mutation:

{% assign data = { "first_name": "Michael", "id": "0386676" } %}

{% graphql notify = "send_api_call", data: data %}

Step 3: Connect the notification to the sign-up form

Connect the API Call Notification you created with the sign-up form :

api_call_notifications:
  - ping_example_com_on_user_sign_up

Whenever a user successfully signs up, the 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