Skip to Content
Webhooks

Webhooks API

Subscribe an HTTPS URL to events in your Prospeo workspace (deals, contacts, accounts, lists, sequences, emails, replies, calls, meetings, recordings, tasks, forms, imports, enrichment, mailboxes and CRM changes). Prospeo sends each event to your URL as a signed POST as soon as it happens.

  • Subscriptions belong to your team. The API key’s user needs the API key view permission to list them, the create permission to create or change them, and the delete permission to delete them.
  • A team can have up to 20 subscriptions.
  • The same five operations are available as tools on the Prospeo MCP server: webhook_event_types_list, webhook_subscription_list, webhook_subscription_create, webhook_subscription_update and webhook_subscription_delete.

Webhooks are free and use no credits.

Request and response format

Every webhook endpoint takes a JSON body and the X-KEY header, and uses POST.

{"ok": true, "summary": "Webhook subscription created. The signing secret is shown only once.", "payload": { ... }}

Errors return HTTP 400 (or 429 for rate limits):

{"ok": false, "code": "NOT_RESOLVED", "message": "Use an https:// URL.", "retryable": false}
HTTP codecodeMeaning
400INVALID_API_KEYInvalid API key, check your X-KEY header.
400INVALID_ARGSThe body has an unknown field, a value of the wrong type, or a query string.
400NOT_RESOLVEDThe request can’t be done as asked; message says why (for example, the URL is not HTTPS, an event type is unknown, the team already has 20 subscriptions, or the subscription id is not one of your team’s).
400PERMISSION_DENIEDThe API key’s user lacks the API key permission this operation needs.
429RATE_LIMIT_EXCEEDEDYou hit the rate limit for your plan.

List event types

Returns every event type you can subscribe to, with its label, family and the kinds of record it is about. The full list is below.

{ "ok": true, "summary": "71 webhook event types are available.", "payload": { "event_types": [ {"event_type": "DEAL_WON", "label": "Deal won", "family": "deal", "subjects": ["deal"]} ] } }

Create a subscription

ParameterTypeRequiredDescription
urlstringYesWhere events are sent. Must be https:// on the default port (443), at a public address, without credentials in the URL. Up to 2,000 characters.
all_eventsbooleanNotrue to receive every event type, including ones added later. Default false.
event_typesarray of stringsWhen all_events is falseEvent types from the list. Up to 200.
{ "url": "https://hooks.example.com/prospeo", "event_types": ["DEAL_WON", "DEAL_LOST", "TASK_CREATED"] }
{ "ok": true, "summary": "Webhook subscription created. The signing secret is shown only once.", "payload": { "webhook_subscription_oid": "6a1b2c3d4e5f60718293a4b5", "url": "https://hooks.example.com/prospeo", "all_events": false, "event_types": ["DEAL_LOST", "DEAL_WON", "TASK_CREATED"], "enabled": true, "created_at": "2026-11-12T14:53:29.807765", "last_failure": null, "signing_secret": "whsec_..." } }

signing_secret is returned only in this response. Store it to verify deliveries. If you lose it, delete the subscription and create a new one.

List subscriptions

Returns your team’s subscriptions in payload.webhook_subscriptions, in the same shape as the create response but without signing_secret. last_failure is null, or the most recent delivery that failed:

"last_failure": { "at": "2026-11-12T14:57:47.610000", "event_type": "DEAL_CREATED", "reason": "The endpoint answered HTTP 500." }

Update a subscription

ParameterTypeRequiredDescription
webhook_subscription_oidstringYesThe subscription to change.
urlstringNoA new URL, with the same rules as on create.
all_eventsbooleanNoSwitch between all events and a chosen list.
event_typesarray of stringsNoReplace the chosen event types.
enabledbooleanNofalse pauses deliveries without deleting the subscription; true resumes them.

Send only the fields you want to change. The signing secret does not change. Returns the updated subscription.

Delete a subscription

ParameterTypeRequiredDescription
webhook_subscription_oidstringYesThe subscription to delete.

Deliveries stop within 30 seconds.

Receiving events

Each event is a POST to your URL with a JSON body:

HeaderValue
Content-Typeapplication/json
User-AgentProspeo-Webhooks/1
X-Prospeo-EventThe event type, for example DEAL_WON.
X-Prospeo-DeliveryAn opaque id for the event. It is the same every time the same event is sent to the same subscription.
X-Prospeo-TimestampUnix time in seconds when this attempt was signed.
X-Prospeo-Signaturev1= followed by the hex HMAC-SHA256 signature.
{ "id": "evt_3f9a1c27b84e4d0c9e2f6a51d7b08c43", "type": "DEAL_WON", "occurred_at": "2026-11-12T15:05:39.502574", "subject": { "deal_oid": "6a1b2c3d4e5f60718293a4b7" }, "data": { "deal_oid": "6a1b2c3d4e5f60718293a4b7", "pipeline_oid": "6a1b2c3d4e5f60718293a4b8", "pipeline_oids": ["6a1b2c3d4e5f60718293a4b8"], "from_stage_oid": "6a1b2c3d4e5f60718293a4b9", "from_stage_oids": ["6a1b2c3d4e5f60718293a4b9"], "to_stage_oid": "6a1b2c3d4e5f60718293a4ba", "to_stage_oids": ["6a1b2c3d4e5f60718293a4ba"] } }
PropertyTypeDescription
idstringThe event’s opaque id, the same as X-Prospeo-Delivery.
typestringThe event type.
occurred_atstringWhen it happened, ISO 8601 in UTC.
subjectobjectThe record the event is about, by id (for example deal_oid, person_oid, company_oid, task_oid, meeting_oid or mailbox_oid), plus email or domain when known.
dataobjectWhat changed. The fields depend on the event type; ids are always *_oid values you can use with the API.

Reply with any 2xx status within 5 seconds. Do slow work after you respond.

Verify the signature

Compute the HMAC-SHA256 of "<X-Prospeo-Timestamp>.<raw request body>" with your signing secret and compare it with X-Prospeo-Signature. Use the raw body bytes, before parsing the JSON. Reject requests whose timestamp is more than 5 minutes old.

import crypto from "node:crypto"; function isValidProspeoWebhook(rawBody, headers, secret) { const timestamp = headers["x-prospeo-timestamp"]; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const expected = "v1=" + crypto .createHmac("sha256", secret) .update(`${timestamp}.`) .update(rawBody) .digest("hex"); const received = headers["x-prospeo-signature"] || ""; return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)); }

Delivery and retries

  • An attempt that gets no 2xx within 5 seconds is retried once, about a second later.
  • If the retry fails too, the event is dropped and recorded as the subscription’s last_failure. Failed events are not sent again later, and there is no replay.
  • A slow endpoint can receive the same event twice: the first attempt may have reached you after the timeout. Use X-Prospeo-Delivery to ignore an event you have already handled.
  • Events from the same record can arrive out of order. Use occurred_at to order them.
  • Redirects are not followed.

Event types

These are the event types available today. Call List event types for the current list.

Event typeFires whenFamilyAbout
CALL_LOGGEDCall loggedcallsaved contact
crm_lifecycle_changedCRM lifecycle stage changedcrmsaved account, saved contact
crm_membership_addedAdded to a CRM segmentcrmsaved account, saved contact
crm_membership_removedRemoved from a CRM segmentcrmsaved account, saved contact
crm_owner_changedCRM owner changedcrmsaved account, saved contact
crm_property_changedCRM field changedcrmsaved account, saved contact
crm_record_convertedCRM lead convertedcrmsaved account, saved contact
crm_record_createdCRM record createdcrmsaved account, saved contact
crm_record_deletedCRM record deletedcrmsaved account, saved contact
crm_record_linkedCRM record linked to Prospeocrmsaved account, saved contact
crm_record_mergedCRM records mergedcrmsaved account, saved contact
ENRICHMENT_COMPLETEDEnrichment completeddatasaved account, saved contact
IMPORT_COMPLETEDImport completeddatasaved account, saved contact
DEAL_COMPANY_SETDeal company setdealdeal
DEAL_COMPANY_UNSETDeal company unsetdealdeal
DEAL_CONTACT_LINKEDDeal contact linkeddealdeal
DEAL_CONTACT_UNLINKEDDeal contact unlinkeddealdeal
DEAL_CREATEDDeal createddealdeal
DEAL_FILE_ADDEDDeal file addeddealdeal
DEAL_LOSTDeal lostdealdeal
DEAL_OWNER_CHANGEDDeal owner changeddealdeal
DEAL_PIPELINE_MOVEDDeal pipeline moveddealdeal
DEAL_REOPENEDDeal reopeneddealdeal
DEAL_STAGE_CHANGEDDeal stage changeddealdeal
DEAL_WONDeal wondealdeal
EMAIL_BOUNCEDEmail bouncedemailsaved contact
EMAIL_NOT_SENTEmail not sentemailsaved contact
EMAIL_REPLIEDReply receivedemailsaved contact
EMAIL_SENTEmail sentemailsaved contact
EMAIL_UNSUBSCRIBEDEmail unsubscribedemailsaved contact
FORM_SUBMITTEDForm submittedformsaved contact
LIVE_ALERT_CLAIMEDLive alert takenformsaved contact
ADDED_TO_LISTAdded to listlistsaved account, saved contact
REMOVED_FROM_LISTRemoved from listlistsaved account, saved contact
MAILBOX_AUTO_PAUSEDMailbox auto pausedmailboxmailbox
MAILBOX_HEALTH_CHANGEDMailbox health changedmailboxmailbox
MEETING_BOOKEDMeeting bookedmeetingmeeting, none, saved account, saved contact
MEETING_CANCELEDMeeting canceledmeetingmeeting, none, saved account, saved contact
MEETING_NO_SHOWMeeting no showmeetingmeeting, none, saved account, saved contact
MEETING_NO_SHOW_UNMARKEDMeeting no-show removedmeetingmeeting, none, saved account, saved contact
MEETING_RESCHEDULEDMeeting rescheduledmeetingmeeting, none, saved account, saved contact
ACCOUNT_CREATEDAccount createdrecordsaved account
COMPANY_OWNER_CHANGEDAccount owner changedrecordsaved account
COMPANY_STAGE_CHANGEDCompany stage changedrecordsaved account
PERSON_ACCOUNT_LINKEDContact linked to an accountrecordsaved contact
PERSON_ACCOUNT_UNLINKEDContact unlinked from its accountrecordsaved contact
PERSON_JOB_CHANGE_APPLIEDJob change appliedrecordsaved contact
PERSON_OWNER_CHANGEDContact owner changedrecordsaved contact
PERSON_STAGE_CHANGEDPerson stage changedrecordsaved contact
RECORD_CREATEDRecord createdrecordsaved contact
RECORD_UPDATEDRecord updatedrecorddeal, saved account, saved contact
RECORDING_FAILEDRecording failedrecordingmeeting, saved contact
RECORDING_READYRecording readyrecordingmeeting, saved contact
REPLY_CATEGORIZEDReply categorizedreplysaved contact
REPLY_MACHINE_OUTCOMEReply machine outcomereplysaved contact
REPLY_RULE_FIREDReply rule firedreplysaved contact
ADDED_TO_SEQUENCEAdded to sequencesequencesaved contact
FINISHED_SEQUENCEFinished sequencesequencesaved contact
FIRST_SEQUENCE_STEPFirst sequence stepsequencesaved contact
SEQUENCE_CONTACT_MAILBOX_CHANGEDContact moved to another mailboxsequencesaved contact
SEQUENCE_CONTACT_PAUSEDSequence contact pausedsequencesaved contact
SEQUENCE_CONTACT_RESUMEDSequence contact resumedsequencesaved contact
SEQUENCE_PAUSEDSequence pausedsequencenone
SEQUENCE_STEP_COMPLETEDSequence step completedsequencesaved contact
TASK_ARCHIVEDTask archivedtasktask
TASK_AUTO_SKIPPEDTask auto-skippedtasktask
TASK_COMPLETEDTask completedtasktask
TASK_CREATEDTask createdtasktask
TASK_DUE_DATE_CHANGEDTask due date changedtasktask
TASK_PRIORITY_CHANGEDTask priority changedtasktask
TASK_REASSIGNEDTask reassignedtasktask

If you need further assistance, feel free to reach out via the chat widget on our website.

Last updated on