Using Webhooks

SalesMind AI can send event data to your server the moment something happens — a connection request goes out, a prospect accepts, a message is sent or received, or a conversation gets tagged. Instead of polling the API, your endpoint gets a POST request with the full context.

This guide shows you how to set up a webhook endpoint, pick the events you care about, and handle the payload.

Prerequisites

• A SalesMind AI account with at least one active sender
• A publicly accessible HTTPS endpoint that can receive POST requests

How webhooks work

SalesMind AI fires a webhook whenever a relevant event happens on a conversation thread in your inbox — whether triggered by a campaign action or a manual change you make in the UI. Each event sends an HTTP POST request to the URL you set up.

Available event types

Event type	Fires when…
activity.invitation.sent.v1	A connection request is sent to a prospect
activity.connection.accepted.v1	A prospect accepts your connection request
activity.message.sent.v1	A message is sent to a prospect (including automated campaign messages and follow-ups)
activity.message.received.v1	A prospect replies to your conversation
activity.threadbox.tags.update.v1	A tag is added or removed on a conversation thread

These five activity.* events are what a normal account can subscribe to and receive. A sixth event, user.register.v1, exists but is admin-only — normal accounts never receive it, and it's removed automatically if you try to subscribe to it. webhook.test.v1 is a one-off event sent by the Test button, not something you subscribe to.

Set up your webhook endpoint

1. In the left sidebar, click the Settings gear icon at the bottom.
2. Click Webhooks.
3. Paste your HTTPS endpoint URL.
4. Pick the event types you want to receive.
5. Select which agents you want to receive events from.
6. Click Save.

💡 Tip: Use the Test button to send a sample payload to your endpoint. This confirms your server can receive requests before any real events fire.

Manage endpoints with the API

You can manage webhook endpoints over the API instead of the UI. Every endpoint needs your X-API-KEY header and lives under https://api.sales-mind.ai//v1/webhooks.

Method	Endpoint	Purpose
POST	/v1/webhooks/endpoints	Register a new endpoint
GET	/v1/webhooks/endpoints	List your endpoints
GET	/v1/webhooks/endpoints/{id}	Get one endpoint
DELETE	/v1/webhooks/endpoints/{id}	Delete an endpoint
GET	/v1/webhooks/endpoints/{id}/rotate-secret	Get a fresh signing secret
PUT	/v1/webhooks/endpoints/{id}/suspend	Suspend or resume an endpoint
GET	/v1/webhooks/events	List the events you can subscribe to
PUT	/v1/webhooks/endpoints/{id}/events	Change the subscribed events
GET	/v1/webhooks/endpoints/{id}/test	Send a test delivery

⚠️ Registration does not return your signing secret. After you register an endpoint, call rotate-secret to retrieve the secret you use to verify deliveries.

Your endpoint must be a public HTTPS URL. SalesMind AI checks this when it delivers an event, not when you register — so a non-HTTPS or private URL is accepted at first and then fails on delivery.

Understand the payload

Every webhook delivery sends a JSON object with three top-level fields and a nested data object containing the full context.

Top-level fields:

Field	Description	Example
id	Unique delivery ID (used as idempotency key)	df313559-7cb1-...
type	The event type	activity.connection.accepted.v1
timestamp	When the event occurred (ISO 8601)	2026-02-06T05:05:36+01:00

The data object contains these sections:

Section	What it contains
data.agent	Your agent name, company details, services, brand tone of voice, and sales playbook
data.campaign	Campaign ID, name, status, objective, product page URL, landing page URL, and campaign type
data.campaignContact	Contact status in campaign (e.g. invitation_send), last activity details, and terminated flag
data.threadBox	Sender and contact full names, tags array, conversation status, fit score, AI rationale, persona name, and answer status
data.sender	Full LinkedIn profile of the sending account, knowledge base contact info, and MBTI personality analysis
data.contact	Prospect's LinkedIn profile, headline, summary, location, skills, current companies, and MBTI analysis
data.messages	Array of messages in the conversation thread

💡 Tip: The full payload is large and includes the complete agent context. Send a test webhook to your endpoint first, then use that JSON to map only the fields you need in your handler.

Verify the signature

Every delivery carries four headers so you can confirm it really came from SalesMind AI:

Header	Value
Webhook-Signature	Base64-encoded HMAC-SHA256 of the signed string
Webhook-Timestamp	Unix epoch seconds, used inside the signed string
Webhook-Idempotency-Key	{eventId}:{endpointId} — use it to drop duplicate deliveries
Webhook-Key-Id	current — which signing secret was used

The signed string is:

{Webhook-Timestamp}.{endpointId}.{sha256_hex(rawBody)}

Sign the value from the Webhook-Timestamp header, not the ISO timestamp field inside the body — they are different.

To verify a delivery:

1. Read the raw request body, the Webhook-Timestamp header, and the Webhook-Signature header.
2. Compute the SHA-256 hex digest of the raw body, then build {Webhook-Timestamp}.{endpointId}.{sha256_hex}.
3. Compute Base64(HMAC-SHA256(that string, your endpoint secret)) and compare it to Webhook-Signature using a constant-time check.
4. Optionally, reject the delivery if Webhook-Timestamp is older than a window you choose (for example, 5 minutes).

💡 The 5-minute replay window is a check you add on your side. SalesMind AI does not enforce it.

⚠️ After you rotate your secret, update your stored secret promptly. SalesMind AI always signs with the current secret, so deliveries switch to the new secret right away — there is no grace period on the signing side.

Check delivery history

You can check whether a webhook fired and review its delivery status directly in the app. Go to Settings → Webhooks to see recent deliveries, their status codes, and timestamps.

You can also pull deliveries over the API:

Method	Endpoint	Purpose
GET	/v1/webhooks/deliveries	List deliveries (filter by endpointId, status, type)
GET	/v1/webhooks/deliveries/{id}	Get one delivery, including its payload
POST	/v1/webhooks/deliveries/{id}/replay	Replay a delivery as a new event

Each delivery has a status: pending, delivered, failed, or suspended.

How delivery attempts work:

• Each attempt times out after 5 seconds.
• A 2xx response marks the delivery delivered and resets the endpoint's failure counter.
• Any other response — or a timeout — marks it failed and retries with a backoff of 5, 10, 20, 60, then 300 seconds (up to 5 retries, so 6 attempts in total).
• After 10 consecutive failures, SalesMind AI suspends the endpoint automatically. New events for a suspended endpoint are recorded as suspended and skipped until you resume it.

Common pitfalls

"The test works but real events don't fire"

Make sure you have an active campaign with prospects moving through the workflow. Webhooks fire when the system takes an action (sends an invite, sends a message, gets a reply, tags a thread) or when you manually change a tag. If no activity is happening, there are no events to send.

"I'm getting events but the payload is missing fields"

The payload varies slightly by event type. An activity.invitation.sent.v1 event won't have reply-related fields, for example. Check the test payload for your specific event type to see which fields are included.

"The payload is very large"

This is expected. Each delivery includes the full agent context (services, sales playbook, brand tone of voice) so your handler has everything it needs to route and process the event. Parse only the fields you need.

"My endpoint URL was accepted but never receives anything"

Your endpoint must be a public HTTPS URL. SalesMind AI checks this when it delivers an event, not when you register — so a non-HTTPS or private URL passes at first, then fails on delivery. Check your delivery history for failed attempts.

Key takeaways

• Webhooks push real-time data to your server when events happen — both automated campaign actions and manual changes.
• A normal account subscribes to the five activity.* events; user.register.v1 is admin-only and webhook.test.v1 is only the test event.
• Manage endpoints, events, and deliveries over the API under https://api.sales-mind.ai//v1/webhooks — authenticate with X-API-KEY.
• Verify each delivery with the Webhook-Signature and Webhook-Timestamp headers; the signing secret comes from rotate-secret, not registration.
• Deliveries retry with backoff and an endpoint is suspended after 10 consecutive failures — review and replay from the delivery history.

FAQ

Which events can my account receive? Normal accounts receive the five activity.* events. user.register.v1 is admin-only, and webhook.test.v1 is only the test event.

How do I verify a webhook came from SalesMind AI? Recompute the signature from the raw body and the Webhook-Timestamp header, then compare it to the Webhook-Signature header. See "Verify the signature" above.

How do I get my signing secret? Registration does not return it. Call the rotate-secret endpoint to get a fresh secret, and update your stored copy right away.

Why was my endpoint suspended? SalesMind AI suspends an endpoint after too many failed deliveries in a row — 10 by default. Fix your server, then resume the endpoint.

Can I resend a webhook I missed? Yes. Use the replay endpoint to send a past delivery again as a new event.

My URL was accepted but no events arrive. Why? The HTTPS and public-URL check runs at delivery time, not at registration. A bad URL passes at first, then fails on delivery. Check your delivery history.