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.
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.