Overview
Webhooks let your own application, agent, or bot get notified the moment something happens in Pronto. A new message, an edit, a deletion, or a user coming online triggers an HTTPS POST to a URL you choose.
Who can set up Webhooks
You must be an organization admin, though once a webhook has been established, you can share it with those who are not administrators.
Custom integrations is not turned on by default. If you do not see Webhooks as an option in your settings as an admin, please contact your Customer Success Manager.
Your personal, Pronto account must have an email address. Pronto uses this to email you if your webhook endpoint starts failing (i.e. when deliveries consistently fail, or an endpoint gets disabled.) If your account only has a phone number, add an email in Org Management first.
Webhooks belong to you, not your whole organization
Webhooks are set up per admin account. Each admin who enables webhooks gets their own set of endpoints, and they only see events they're allowed to see (see Which events you'll receive). Many organizations create a dedicated admin account for a bot or integration and set up webhooks on that account.
What's handled for you
After webhooks are enabled, everything is managed from the Webhooks screen in Pronto: adding endpoints, choosing events, sending test events, viewing delivery logs, and retrying failed deliveries. Failed deliveries are retried automatically.
Setting up webhooks
You can set up webhooks in a few minutes from the Pronto web app. Use the web app at app.pronto.io; webhooks cannot be managed from the mobile apps.
Sign in to the Pronto web app with your admin account.
Open Settings, then select Webhooks.
Don't see Webhooks? Check that you're an organization admin and that integrations are enabled for your organization. If you are unclear about either of those things, please chat with us at pronto.io
Click Enable Webhooks. This is only needed the first time.
If you see an Email Needed message, add an email address to your account in Org Management, then try again.
Wait a moment while Pronto sets things up. The webhooks dashboard then opens.
Click Add Endpoint, enter the URL that should receive events, and choose which events to subscribe to. Leave the events unselected to receive all of them.
Full walkthrough: Adding Endpoints
Copy the endpoint's Signing Secret. Your application uses it to confirm each webhook really came from Pronto (see Verifying, testing, and troubleshooting).
Send a test event from the endpoint's Testing tab to confirm everything works.
Full walkthrough: Testing Events
No server yet? Svix Play gives you a temporary URL that shows incoming webhooks in your browser, which is useful for seeing real payloads before you write any code.
Which events you'll receive
Your webhooks only receive events you could see yourself in Pronto. You don't get a copy of every message in your organization.
What's delivered
Here are some examples of events you might receive:
Example event | Delivered when |
A message is created, edited, or deleted | The message is in a chat you're a member of. Messages in a thread are delivered if you're a member of the thread's parent chat. |
A user comes online or goes offline | Any user in your organization comes online or goes offline. |
For the full, current list of event types, see the Event Catalog in the Webhooks screen (see Event types and payload formats).
To receive messages from a chat, add the webhook owner's account to that chat. Removing the account from the chat stops those deliveries.
Narrowing deliveries with tags
Every event is labeled with Tags. You can set an endpoint to only receive events with certain tags.
Tag | Matches |
| Messages in that chat, including its threads |
| Messages in that thread |
| Messages sent by that user, plus that user's presence events |
| Messages that @mention you directly (not @everyone) |
An endpoint receives an event if it matches any of the endpoint's tags.
An endpoint with no tags receives everything you have access to.
Tags are exact and case-sensitive, for example
chat_12345.You can also limit an endpoint to certain event types. An event must match both the event types and the tags you've set.
Event types and payload formats
The current list of event types, each event's payload format, and an example payload are in the Event Catalog in the Webhooks screen. The catalog is always up to date, so check it rather than relying on a saved copy.
Open Settings, then Webhooks.
Click the Event Catalog tab.
Select an event type to see its description, schema, and an example payload.
More about the catalog: Event Catalog
A few tips for building against payloads:
New event types and new fields may be added over time. Ignore event types and fields your application doesn't recognize instead of failing.
Messages in a thread carry the thread's ID as their chat ID. The included chat details show whether it's a thread and which chat it belongs to.
Message payloads include a
conversation_id, which stays the same across a message and its replies or thread. Bots can use it to keep track of a conversation.message.deletedevents include only the IDs needed to identify the deleted message.
Verifying, testing, and troubleshooting
Pronto webhooks are delivered by Svix. Svix's documentation for webhook receivers applies to Pronto as written, so these links cover the details.
Verify every webhook
Each webhook is signed with your endpoint's Signing Secret. Check the signature before trusting a payload, so no one else can send fake events to your URL. The webhook-id, webhook-timestamp, and webhook-signature headers are what you check.
How to verify webhooks (ready-made libraries for most languages)
Manual verification (if you can't use a library)
Respond quickly
Return a 2xx status within a few seconds, then do any slow work afterward. Other responses or timeouts count as failures and are retried. Duplicate deliveries can happen, so use the webhook-id header to skip events you've already handled. Background: Receiving webhooks.
Test, inspect, and replay
Task | Where | Guide |
Send a test event | Endpoint → Testing tab | |
See what was delivered and the response | Endpoint → Logs | |
Resend failed or missed events | Endpoint → Logs |
If deliveries keep failing
After repeated failures, an endpoint may be disabled automatically and you'll get an email at the address on your account. Fix the problem on your server, re-enable the endpoint in the Webhooks screen, and replay the missed events.
Firewall allowlisting
If your server only accepts traffic from known addresses, see Static Source IP Addresses.
Still stuck?
Contact Pronto support with your endpoint URL and the message ID from the delivery log.