Easy Webhook for lookups

Sept. 29, 2015

RapidPro allows you to compare response against predefined parameters. For example, if you’re asking for a user's gender, you can indicate that a response containing words such as “female”, “woman”, “girl”, “mother”, etc., should be categorized as Female and “male”, “man”, “boy”, etc., as Male.

However, this approach is not ideal in cases where you want to check a response against a long list of categories while at the same time allowing for responses to be misspelled. You could still follow the above approach but it would be tiresome: for each name you need to define a category and for each category you need to come up with potential matches to allow for misspellings, which of course can be infinite.

To solve this problem you can use the RapidPro webhook functionality. A webhook is a method of getting or posting information between a web page and a web application. In RapidPro, webhooks can be used to send, receive, or verify information from a third-party source.

This is how it works:

1.       A flow in RapidPro calls the webhook and passes it some text in the webhook itself and says which dataset to use.

2.       The webhook processes the text by comparing it against the dataset at for example nomenklatura.uniceflabs.org.

3.       The webhook responses with the best match or null if there is no match.

4.       The flow can then update anything it wishes based on the match.

How to use it:

1. Prepare a dataset in CSV format. The dataset should usually be one column of something to look up, like location names. The dataset can be prepared in Excel and exported as a CSV.

2.  Creating a webhook dataset requires a GitHub account (www.github.com) if you want to use nomenklatura.uniceflabs.org to host your dataset . Create a GitHub account or use your own.

3. Visit nomenklatura.uniceflabs.org and add the dataset:

a. Choose 'Create a dataset'. The title can have spaces, but the slug should not. The slug is what you will put into the webhook. Click to create the dataset.

b. On your dataset page for the new dataset, choose 'Import'. Once on the import page, choose the columns to import. Import the column which has the names being looked up as Core Attributes-->Name (Required). Then click on 'Load Entities'.

c. Go back to the home page and you should see the dataset listed.

4. Go the RapidPro workspace flow which will use the webhook.

5. After sending a message, the next flow step should be to 'Wait for Response' and the result saved name, e.g. districtname.

6. The next flow step is the 'Make call to external server'. On that flow step, leave GET as the request type. The URL template is: 


where you replace the slug name with yours. The template uses districtname as the variable containing the text being passed to the webhook. If the flow step before uses a different name for saving the responses, then use that name.

7. The response from the webhook will be @extra.match This can be referenced in flows, e.g. to update contact information.

8. Test the webhook in the simulator.



The instructions above are illustrated in the example below (thanks to Elliot McBride / Innovation Lead UNICEF Pakistan). In this example, Elliot wants to match a user response with a district name against an official list of Pakistan districts. 

1. Upload the list of Pakistan districts onto nomenklatura.uniceflabs.org following the instructions above.  

2. Create the flow and ask the relevant question i.e. which district are you in?


3. Draw line to the next command and select ‘wait for response’. Then select the message response criteria as ‘has any of these words’ and leave this field blank saving the ‘result’ as your topic i.e. districtname:


Note: district is already defined in RapidPro. Please use districtname as an alternative. 

4.       The next rule select dropdown box ‘make call to an external server’. There will be a space for your webhook URL. Select ‘GET’ on the dropdown box next to the webhook URL, and click OK.


5.       Finally to check the user has entered the correct response check with them using the group ‘@extra.match’ send a text such as the following.


6.       Send confirmation message using the group @extra.match


7.       Overall your webhook flow should look similar to this: