Guide to Outgoing Webhooks for System Integration

Outgoing Webhooks allow ABC Sales Bot to send real-time notifications to your external systems whenever specific events occur. This feature is essential for businesses that need to keep data synchronized across multiple platforms, such as a CRM, an inventory management system, or a custom analytics dashboard.

Instead of constantly polling our API for changes (which is inefficient), you can subscribe to events. When an event happens, like a lead being created or updated, we instantly push the relevant data to a URL you provide.

Key Use Cases

• Real-time CRM Sync: instantly create or update a contact in your CRM (e.g., Salesforce, HubSpot) the moment a lead is created or modified in ABC Sales Bot
• Automated Fulfillment & Operations: trigger a process in your internal system, such as assigning a new lead to a regional sales team or starting a welcome sequence in your marketing platform
• Centralized Data Warehousing: push all lead and conversation data to a centralized analytics platform (like Google BigQuery or a custom dashboard) for advanced reporting
• Custom Notifications: send tailored notifications to team communication platforms like Slack or Microsoft Teams when important events happen, like a lead being escalated

How to Configure an Outgoing Webhook

Setting up a webhook is a straightforward process.

1. Navigate to the Outgoing Webhooks tab from the main menu
2. Click the Create Webhook button
3. A configuration window will appear, fill in the details below
4. Click Create Webhook to save and activate it

Configuration fields:

• Webhook URL (Required): the most important field. Enter the unique URL of your external system that is set up to receive incoming data.
• Event Types: select the specific events you want to subscribe to. You can subscribe to a single event or all of them.
• Custom Headers (Optional): add static header values to your webhook requests, useful for authentication or routing on your server.
• Max Retries: the number of times we will try to resend the event if your service is down or returns an error. The retries use an exponential backoff strategy to avoid overwhelming your system.
• Max Concurrency: the number of concurrent webhooks we can send at one time. The default is usually sufficient for most use cases.

Key event types include:

• leads_created
• leads_updated
• leads_deleted
• leads_escalation_requested
• conversation_created

You can create multiple webhooks, for instance, if you want to send different events to different systems.

Security: Verifying Payloads with the Secret Key

To ensure that the requests your server receives are genuinely from ABC Sales Bot, we sign each webhook payload.

Viewing the Secret Key

1. On the Outgoing Webhooks page, click the three-dot menu next to your webhook and select Edit
2. Click Show Secret Key
3. This key is unique to your webhook. You must use this key on your server to verify the signature of the incoming payload

Verification Logic

We include a cryptographic signature in the header of each request. Your server can use the shared secret key to recalculate the signature from the request body. If the signatures match, you can be certain the request is authentic and has not been tampered with.

Regenerating a Key

If you believe your key has been compromised, you can regenerate it at any time. Remember to update the key on your server after regenerating it.

Understanding the Payload

When an event is triggered, we send a POST request to your URL with a JSON body. The payload always contains:

• event_type: the name of the event that occurred (e.g., leads_updated)
• company_id: your company's unique identifier
• The relevant object data: for leads_created and leads_updated this is the entire lead object; for leads_deleted we only send the lead_id, as the full object no longer exists

Troubleshooting: The Webhook Log

To diagnose any issues with your webhook delivery, a detailed log is available for each endpoint.

1. Click on a configured webhook from the main list
2. This opens the Webhook Log view, which shows a history of all events sent to that URL

For each event, you can see:

• Status: a green check for success or a red warning for failure
• Attempts: the number of retries made
• Request Duration: how long your system took to respond. This is useful for identifying slow performance or timeouts on your end
• View Details: click this to inspect the exact Request Payload we sent and the Response Body (and status code) we received from your server. This is invaluable for debugging as it shows you precisely what went wrong if an error occurred