Webhooks API

Webhook endpoints are public (no authentication required) and are mounted under /api/webhooks. They are called by external services.

Reverse Contact

Profile Change Alert

POST /api/webhooks/reversecontact

Receives profile change alerts from Reverse Contact for monitored LinkedIn profiles. Validates the subscriptionId against known people records, computes a diff against the previous snapshot, and stores the alert.

Body:

Field	Type	Required	Description
subscriptionId	string	Yes	Reverse Contact subscription ID (must match a person’s alert_subscription_id)
data.person	object	No	Updated profile data

Response: { ok: true }

Error responses:

• 400 — Invalid JSON or missing subscriptionId
• 404 — Unknown subscription ID

---

Resolve Callback

POST /api/webhooks/reversecontact/resolve

Receives async resolve results from Reverse Contact when an email-to-LinkedIn lookup completes. Updates the target entity (company, contact, or person) with the resolved LinkedIn URL and triggers full profile enrichment.

Query parameters:

Param	Type	Description
type	string	Entity type: company, contact, or person
id	string	Entity ID to update

Body: Reverse Contact resolve payload containing data.linkedinUrl or data.linkedInUrl.

Behaviour by entity type:

• company — Saves LinkedIn URL, fetches full company profile (description, logo, specialties), uploads logo to R2 if available.
• contact — Saves LinkedIn URL, triggers LinkedIn profile enrichment, uploads profile picture to R2.
• person — Saves LinkedIn URL, triggers LinkedIn profile enrichment.

Response: { ok: true }

---

Twilio

Message Status Callback

POST /api/webhooks/twilio/message-status

Receives delivery status updates from Twilio for outbound messages. Validates the request using HMAC-SHA1 signature verification.

Headers:

Header	Description
X-Twilio-Signature	HMAC-SHA1 signature for request validation

Form body (from Twilio):

Field	Description
MessageSid	Twilio message SID
MessageStatus	Status: queued, sent, delivered, failed, etc.
ErrorCode	Error code (if applicable)

Response: 204 No Content

Error responses:

• 403 — Missing or invalid Twilio signature
• 400 — Missing required fields
• 500 — Twilio not configured

---

Inbound Message

POST /api/webhooks/twilio/inbound

Receives inbound SMS and WhatsApp messages from contacts. Validates the Twilio signature, matches the sender’s phone number to a contact record, and stores the message.

Headers:

Header	Description
X-Twilio-Signature	HMAC-SHA1 signature for request validation

Form body (from Twilio):

Field	Description
From	Sender phone number (may include whatsapp: prefix)
To	Recipient phone number
Body	Message text
MessageSid	Twilio message SID
NumMedia	Number of media attachments
MediaUrl0	First media URL (if present)

The sender is matched against contact_relationship_profiles.phone_number, contact_relationship_profiles.whatsapp_number, contacts.mobile, and contacts.phone.

Response: Empty TwiML response (<Response></Response>) — no auto-reply is sent.

Error: 403 if signature validation fails.