Skip to main content

What are "Event Endpoints"?

Whenever an event takes place within Prompt.io (e.g., a new customer is added, they opt out, a message is received, a broadcast completes, etc.), that event, and its associated data, can be captured in real-time like a webhook, using Prompt.io’s “Event Endpoints.”

With these webhook events, you can program an application to perform external actions. Examples of ways customers have used this functionality include:

  • Updating their CRM

  • When a contact opts out, remove them from an email list

  • Post to Slack when a Broadcast changes state

  • When a customer clicks on a Smartlink, send the contact an email, then schedule a meeting and create a calendar entry

  • The first time a customer replies, post information to Zapier and use Zapier to create a row in a Google Spreadsheet.

The possibilities for extending the functionality of Prompt.io using Event Endpoints is endless, and it isn’t as technically challenging as it may appear.

💗 Let’s get started using Event Endpoints! 💗

STEP 1. Set up Server to handle webhooks

First, ensure you have Node.js and npm installed on your machine. Open your terminal or command prompt and run the following commands to set up a basic Express server. This server will listen for incoming webhook events, or "Event Endpoints" as we call them in Prompt.io.

Let’s create a folder called webhook-listener

server code

In a code editor, paste the above Node.js script into server.js, and lets set it to run locally on port 80

start server

Now start your server

STEP 2. Expose Your Local Server with ngrok

For development testing, using a service like ngrok, you can setup a static domain and establish a tunnel with your local server, bridging your local development environment with external webhook events without deploying.

Let’s say your public URL is https://mypromptserver.ngrok.app

First setup the tunnel. We’ll use localhost port 80

If everything is set up correctly, when you visit https://mypromptserver.ngrok.app in your browser, you should see a page saying “Webhook Listener Running”

STEP 3. Subscribe to Event Endpoints

In the Full Suite of Prompt.io, go to the Hamburger Menu in the top-left corner > Developer Tools > Event Endpoints.

If you don't have access to the Developer Tools menu item, get in contact with your Customer Success Manager, who can help you retrieve those tools.

Click Add Event Endpoint

set identifier & url

Give it a name, and enter your public URL

subscribe to events

When you click save, you’ll see a bunch of event routes you can subscribe to. Let’s subscribe to some commonly used ones:

Select /message/added, /message/status, /customer/added, /customer/optOut, /contactAction, /broadcast/statusChanged, & /smartlink/clicked

Once you hit save, every time these events occur in the product a payload will be posted to your public url endpoint.

STEP 4. Build Out the Webhook Routes

To view those payloads, in your server application, you can implement each corresponding route like so

STEP 5. Add Authentication

It’s recommended that you add authentication to the application. To do this, in the product, select an authentication type. We offer Basic Auth, X-Hub-Signature, & Custom Header validation methods. It is up to you to implement this to your system needs. For demonstration purposes, we’ll take a naive approach, and create a simple custom token by setting the key to webhooktoken and provide a value that our server will expect. This should be a secure unique token, but for this example, we’ll set it to abcdefg.

validator function

In our server, let’s add a function to validate the requests.

pass function into route

And on each route definition, we can pass in that function

finished code

Finally, our server.js code should look like this

STEP 6. Test Your Application

To test, make sure your ngrok tunnel is active

save & run server

and that you saved and ran the node code

start testing

Now we can test each action!

Run a broadcast to send a text to yourself. Reply to the text, opt out, opt in, click a smartlink, etc.

While performing these actions, observe the terminal console, where you will find the payloads of the Event Endpoints.

For example, A received message should look like this (above)

broadcast state change payload

A broadcast status change should look like this

smartlink clicked payload

A clicked smartlink should look like this

Next Steps…

Needless to say, now that you can ingest these events, you can use them as triggers for anything you want! For example, whenever the "/customer/added" endpoint is hit, you can fetch a random dog picture from the Dog CEO's Dog API and then process it according to your needs (e.g., set a dog picture as the avatar of a customer in an external CRM.).

Here's how you could implement this in your server

need help?