Use this guide to send Fin's integration errors to your own systems as they happen. When you add a webhook, Fin sends a signed POST request to your URL each time a new error appears in Error logs, so you can route it to your alerting, ticketing or monitor.
Note: Error logs webhooks are available for Fin for platforms workspaces connected to Salesforce, HubSpot, Freshdesk or Zendesk.
Before you begin
You need the Manage apps and integrations permission to add, test or remove the webhook. Without it, you can select Request permission in the Webhook panel.
Your endpoint must be publicly reachable over HTTPS. When you save, Fin sends a HEAD request to check that it's reachable.
Your endpoint should return a 2xx status code within 7 seconds.
How to add a webhook
Go to Settings > Error logs (under Integrations).
Click Webhook in the top right of the page.
In Webhook URL, enter your endpoint, for example
your-server.example.com/error-logs. Thehttps://prefix is added for you.Select Save. You'll see “Webhook saved” when the URL is validated.
(Optional) Copy the Signing secret shown below the URL. You'll use it to verify that requests come from Fin.
Select Test to send a test event to your endpoint. You'll see “Test sent” if your endpoint responds successfully.
Note: The test sends a
pingevent, not an error log. Make sure your endpoint accepts both topics (see the examples below).
What Fin sends to your webhook
Fin sends one request for each new error that appears in Error logs. If the same error repeats for the same conversation within an hour, it may only be logged and sent once.
Each request is a POST with a JSON body and these headers:
Content-Type: application/json
X-Hub-Signature: the request signature (see How to verify the signature).
Intercom-Webhook-Subscription-ID: the ID of your webhook subscription.
Example error log payload
The error details are in data.item. The topic is always error_log.created.
{
"type": "notification_event",
"app_id": "abc123de",
"topic": "error_log.created",
"id": "notif_1a2b3c4d",
"created_at": 1762430400,
"data": {
"type": "notification_event_data",
"item": {
"type": "error_log",
"id": "123",
"app_id": "abc123de",
"created_at": 1762430400,
"environment": {
"type": "environment",
"id": "456",
"name": "acme.my.salesforce.com",
"is_production": true
},
"error_code": "INVALID_FIELD",
"error_message": "No such column 'InvalidField' on entity 'Case'",
"request_status": 400,
"request_method": "POST",
"request_path": "/services/data/v58.0/sobjects/Case",
"object_type": "Case",
"api_type": "salesforce_rest_api",
"product_feature": "salesforce_cases",
"integration_type": "salesforce_cases",
"conversation_id": "789"
}
}
}
Error log fields
id: the ID of the error log entry.
app_id: your Fin workspace ID.
created_at: when the error happened, as a Unix timestamp in seconds.
environment: the connected helpdesk environment, such as your Salesforce org or Zendesk subdomain. Can be null.
error_code: the error code returned by your helpdesk, for example INVALID_FIELD.
error_message: the error message returned by your helpdesk.
request_status, request_method and request_path: the HTTP status, method and path of the request that failed.
object_type: the helpdesk object involved, for example Case or Knowledge__kav.
api_type: the helpdesk API Fin was calling, for example salesforce_rest_api, hubspot_rest_api, freshdesk_rest_api or zendesk_rest_api.
product_feature: the Fin feature affected, for example salesforce_cases, fin_messenger, knowledge_import or historical_conversations_import.
integration_type: the Fin integration the error came from, for example salesforce_cases or zendesk_tickets.
conversation_id: the related Fin conversation, if there is one. Can be null.
Note: These fields match what you see in the Error details panel in Error logs. To understand and fix a specific error code, see Fin for Salesforce: Fix common integration errors.
Important: error_message and request_path come straight from your helpdesk and can include record data, such as field values or IDs. Store payloads securely.
Example test payload
{
"type": "notification_event",
"topic": "ping",
"data": {
"type": "notification_event_data",
"item": {
"type": "ping",
"message": "This is a ping notification test message."
}
}
}
How to verify the signature
Every request includes an X-Hub-Signature header. It's an HMAC-SHA1 of the raw request body, signed with your signing secret, in the format sha1=<hex digest>.
To verify a request:
Compute an HMAC-SHA1 of the raw request body, before parsing the JSON, using your signing secret as the key.
Prefix the hex digest with sha1=.
Compare it with the X-Hub-Signature header using a constant-time comparison. Reject the request if they don't match.
For example, in Ruby:
expected = "sha1=" + OpenSSL::HMAC.hexdigest("SHA1", signing_secret, raw_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Hub-Signature"])Important: Keep your signing secret private. Viewing or copying it is recorded in your workspace's teammate activity log.
Delivery and retries
A delivery counts as successful when your endpoint returns a 2xx status code. Fin doesn't follow redirects, so use your endpoint's final URL.
If your endpoint times out or returns an error, Fin retries the delivery automatically.
If your endpoint returns 410 Gone, Fin stops sending to it straight away.
Fin may send the same event more than once. Use the top-level id of the event to ignore duplicates.
Fin may deliver events out of order. Use created_at to sort them.
Fin sends one request per error, so an outage in your helpdesk can send many requests in a short time. Respond quickly and process events in the background.
Webhook status messages
If deliveries are failing, the Webhook panel shows one of these messages:
Paused: “Your endpoint is returning errors, so deliveries are paused. We’ll retry automatically.” No action is needed if the problem is temporary.
Suspended: “Your endpoint kept returning errors, so deliveries are suspended.” Fix your endpoint, then select Save again to reconnect.
Deactivated: “Your endpoint returned 410 Gone, so deliveries stopped.” Select Save again to reconnect.
Stopped by Fin: “Fin has stopped deliveries to this webhook.” Contact support to resume them.
How to remove a webhook
Go to Settings > Error logs and select Webhook.
Select the trash icon next to the URL.
Select Remove webhook to confirm.
Fin stops sending new error logs to that URL. Any already on their way may still arrive. You can add a webhook again at any time. If you do, a new signing secret is created, so update it in your endpoint.
FAQs
Can I send error logs to more than one URL?
Can I send error logs to more than one URL?
Not yet. Each workspace can have one error logs webhook.
Can I choose which errors are sent?
Can I choose which errors are sent?
No. Fin sends every new error that appears in Error logs. You can filter on fields like product_feature, api_type or error_code in your own system.
Does Fin send past errors when I add a webhook?
Does Fin send past errors when I add a webhook?
No. Only errors logged after you save the webhook are sent.
Why didn't the test send an error log?
Why didn't the test send an error log?
The Test button sends a ping event to check your endpoint is reachable. Real error logs use the error_log.created topic.
Can I change or regenerate the signing secret?
Can I change or regenerate the signing secret?
The secret stays the same while the webhook is set up. To get a new secret, remove the webhook and add it again.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

