Creating an API Call Notification

Last edit: Aug 16, 2019
  • Contributors:
  • pavelloz
  • diana-lakatos
  • Slashek

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

Create an API Call Notification notifications/api_call_notifications/ping_example_com_on_user_sign_up.liquid:


---
name: ping_example_com_on_user_sign_up
to: 'https://example.com/endpoint/{{ form.id }}'
delay: 0
enabled: true
format: http
trigger_condition: true
callback: >
  {% log response, type: 'response object' %}
  {% assign response_hash = response.body | parse_json %}
  {% log response_hash, type: 'response body as hash' %}
request_type: POST
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

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

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.

Important

We do not send real text messages on staging by default. Because any error with sending real text messages on staging might be more costly than sending emails. If you want to test SMS on staging, please change enable_sms_and_api_workflow_alerts_on_staging flag to true in your Partner Portal instance configuration.

Next steps

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

Questions?

We are always happy to help with any questions you may have.