Inbound webhook is a powerful tool to receive data from anywhere to the chatbot through a POST request.

With inbound webhooks, your bot can even start a conversation with a bot user who never talked to it before.

For example, when a client fills in their contact information on your website, you send the data to an inbound webhook of a chatbot, say an SMS bot. The SMS bot can then send a confirmation message to the client's phone number.

If that webhook is built in a Voice bot, the bot can even call the client right away!

Limitation - Each bot has up to 5 inbound webhooks, the rate limits is 500 request per 24 hours.

Create Inbound Webhook

It's available in almost all channels, in your flow builder, go Tools - Inbound Webhooks:

Click on New Inbound Webhook, give a name and click Save:

You will see the editing interface like this:

Webhook Address

This area shows you where to send the data and the method, which is POST. Each inbound webhook has a unique URL in the whole OCP system.

Example of Received JSON

This area shows an example JSON for reference. It describes the structure of the data in the JSON we received later. We need it to find the values for both **user identification ** and data to save.

There are 2 ways to get an example JSON:

1. manually type/paste it here

2. listen to a real-time data from a live test

Values to Identify a User

Whenever the webhook receives data, it first checks the paths you specify here to see whether it can find an existing user in the chatbot.

If the user is not in the system, the chatbot will create a new profile. That's how the chatbot initiates a conversation without talking to the user before.

However, some channels don't allow the chatbot to start the conversation first due to privacy and spam issues.

For example, your SMS bot can send messages as long as you have the recipient's phone number, while your Facebook Messenger chatbot cannot send messages to a Facebook user who never talked to your bot before.

Process for User Identification

This is the process of how the system identifies a user:

1. check user_ns

   • if there is a valid user_ns, user found.

   • if not, next step

2. check phone / email

   • if we can find a user by the phone or email, user found.

   • if not, next step

3. verify phone

   • no user matched in the system, is the phone a valid number?

   • if yes, user profile created.

   • if not, webhook won't be processed

Mapping Area

The mapping list shows which value should be stored in which custom field. When you get a sample JSON in the above area, click on Preview Payload to get a mapping tool.

Webhook Logs

Every single request is saved in Logs. Click on a record to see the received JSON data.

Inbound Webhook Limitation

By default, inbound webhook request limits is 500 request per 24 hours. You can see the limits from the screenshot below:

If you have exceed the limits, you do have the option to upgrade to more request per day, here is a list of the option you have:

• 500/day - Included   ~~   15K requests/per month

• 1000/day - $20 per month   ~~   30K requests/per month

• 2000/day - $40 per month   ~~   60K requests/per month

• 3000/day - $60 per month   ~~   90K requests/per month

• 4000/day - $80 per month   ~~   120K requests/per month

• 5000/day - $100 per month   ~~   150K requests/per month

• 10000/day - $200 per month   ~~   300K requests/per month

You can subscribe from the link below:

https://buy.stripe.com/

The link is $20 per month per unit, If you need 1000 request per day, just select the quantity 1;

If you need 2000 request per day, just select the quantity 2, etc

After the payment, you need to provide your payment receipt and your flowNS to OCP support email at care@alendei.com

Here is how you can find your flowNS,

Go to “All bots” in OCP dashboard, and then find the bot you want to increase the inbound webhook request limits, and then click the dropdown, you will find the flowNS.

How to debug inbound webhook max request error

First of all, if you are not receiving the data in the inbound webhook, or you can’t find the data in the logs, it’s highly possible that you reached the max daily request limits.

Here is how you can test it.

You can send the request to the inbound webhook from Postman or OCP external request, and then you can find the below information in the header:

As you can see, there is rate-limit-remaining, if it’s 0, that means you already reached the rate limits, you should upgrade for more limits.

Demo: Booking Confirmation

A perfect tool to test your inbound webhook is already built-in everywhere! Simple get a chatbot (whatever channel), test it in an Action Step.

Open another OCP webpage side by side, keep the inbound webhook editing on Page 1 and select an external request on Page 2:

Follow steps 1 to 8 in the following screenshot:

Provide the data that need to be sent to the chatbot and click Test, you must get a "webhook inactive" error since we haven't activated it yet. It's fine, click on Done on Page 1, and you will see the data saved:

Scroll down a bit, follow steps 1, 2, 3 to tell the system, where is the phone and email values in the JSON:

Finally, map the rest data to the chatbot:

Save your inbound webhook editing:

Enter the subflow, let's send a message to the bot user:

Publish the flow and let's do a live test in the external request again:

We can see that this time it run without error because we activated the webhook and used a real phone number. Go to Logs and we can see a new user profile is created successfully.

On the user side: