This tutorial walks through how to send a webhook to a prototype, which sends a unique notification to anyone who has the prototype open in review mode. 

The tutorial builds an airline notification, that can be sent unique text content. The tutorial uses a ‘POST webhook’, which sends a message to a URL. This message is used as a trigger in the prototype for a specific action.

Here is a sample, which you can copy into your own account: https://app.atomic.io/d/Fj4sMQuSasxW

To complete this tutorial, you need a platform to send a webhook from. We’ll explain how you can use Postman (a free platform) to send the webhook, but you are also able to apply the principle to a platform you are more comfortable with.

If you don’t already have Postman, we suggest you download it before starting the tutorial.
 

Step 1: Create a component for the notification with placeholder content

First add a rectangle for the background of the notification that is the desired width and height. Our is 375px wide and 80px high to match an iPhone canvas.

On the canvas, add three text elements:

One for the airline name — with the layer name 'appName'

Two for the body of message — with the layer names 'messageLine1' and 'messageLine2'.

Select only the elements that make up the notification, and then click on ‘Create reusable component’ in the top toolbar, or use the keyboard shortcut ⌘3.

Name the component 'notification'. 

Double click on the component instance to open it, and in the pages tab rename the page 'show'. 

Duplicate the first page, delete all of the elements on it, and rename this page to 'hide'. 

Reorder the pages, so that ‘hide’ is on the top. 

Click ‘Back’ to go back to the main level of the prototype. 

Finally for this step, set the state of the notification component to ‘hide’.
 

Step 2: Add a page action for when a webhook is received

Add a page action for when a webhook is received. See how to add a page action

Name the webhook 'flight_notification'.

Using a script expression action, and add the following JavaScript: 

PATH_TO_COMPONENT = SELF.concat(["notification"]);
PATH_TO_APP_NAME_TEXT = PATH_TO_COMPONENT.concat(["show", "appName"]);
PATH_TO_MESSAGE_LINE_1_TEXT = PATH_TO_COMPONENT.concat(["show", "messageLine1"]);
PATH_TO_MESSAGE_LINE_2_TEXT = PATH_TO_COMPONENT.concat(["show", "messageLine2"]);

// Get content of the payload and pass into notification component
text(PATH_TO_APP_NAME_TEXT, webhookPayload.appName);
text(PATH_TO_MESSAGE_LINE_1_TEXT, webhookPayload.messageLine1);
text(PATH_TO_MESSAGE_LINE_2_TEXT, webhookPayload.messageLine2);

// Reveal notification
state(PATH_TO_COMPONENT, "show", "slide-up", "ease-in-out", 300, 0);

 

Step 3: Add a webhook

Open Postman, and in a new tab:

  1. Make a new Post request by changing the type from the default ‘GET’ to a ‘POST’ webhook. 
  2. Switch to the ‘Body’ tab and set the body type to ‘raw’. 
  3. Change the request type from ‘Text’ to ‘JSON (application/json)’. 
  4. Add the following code in the text area provided: 
{
  "messages": [{
    "name": "flight_notification",
    "payload": {
        "appName":"Atomic Air",
        "messageLine1":"Flight boarding!",
        "messageLine2":"Flight NZ007 is now boarding! Go to gate 13."
    }
  }]
}

 

Step 4: Set the request URL 

We need to generate a URL to use as part of the ‘request URL’ in Postman. This is what is sent from Postman to the Atomic prototype. To get that, we first need to get a unique ‘document ID’ from Atomic. 

Go back to Atomic and get the document ID by opening the share-link modal and copying the document ID from the bottom of the modal.

In Postman, paste this ID into the field labelled ‘Enter request URL’ then add https://app.atomic.io/webhooks/  to the start of it. It should look something like this:

https://app.atomic.io/webhooks/93582am7-342n-a349-09y6g4v3s43f

 

Step 5: Add a bearer token

We now need to generate a security ‘authority token’. You need to use your unique Atomic Personal Access token as the Bearer token. 

To access your Atomic Personal Access Token:

  1. From the Hub, select your avatar, and then ‘Personal access tokens’
  2. Select ‘Create a new token’
  3. Name the token anything you like (e.g. ‘Airline prototype’)
  4. Click on ‘View token’ and copy the token ID displayed. 

In Postman, add the token. Within the POST request, switch to the Authorization tab, and then set the type to ‘Bearer Token’. 

Paste the token into the ‘Token’ field, then return to the ‘Body’ section.

Note: treat your Atomic token like a password! Good practice is to revoke a token as soon as you are finished with the prototype, and to generate a new token for each prototype.
 

Step 6: Test it out

Open your prototype in review mode. Now it’s ready to receive the webhook. 

Go back Postman, and click the ‘Send’ button to send the webhook! The notification should display in your prototype.

Try changing the appName, messageLine1 or messageLine2 parts of the request in Postman and sending it again to see how easy it is to send different content to your prototype.

Tips:

  • The notification will be sent to any device that has the share link open at the time. 
  • If you want to use the webhook payload, you’ll be able to access the webhookPayload object in preview/review.
  • The payload in the webhook POST can be empty {} if you don’t plan to do anything except trigger your action.

Did this answer your question?