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_updateandwebhook_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 code | code | Meaning |
|---|---|---|
400 | INVALID_API_KEY | Invalid API key, check your X-KEY header. |
400 | INVALID_ARGS | The body has an unknown field, a value of the wrong type, or a query string. |
400 | NOT_RESOLVED | The 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). |
400 | PERMISSION_DENIED | The API key’s user lacks the API key permission this operation needs. |
429 | RATE_LIMIT_EXCEEDED | You hit the rate limit for your plan. |
List event types
- URL: https://api.prospeo.io/api/v2/tools/webhook-event-types-list
- Method:
POST - Body:
{}
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
- URL: https://api.prospeo.io/api/v2/tools/webhook-subscription-create
- Method:
POST
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Where 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_events | boolean | No | true to receive every event type, including ones added later. Default false. |
event_types | array of strings | When all_events is false | Event 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
- URL: https://api.prospeo.io/api/v2/tools/webhook-subscription-list
- Method:
POST - Body:
{}
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
- URL: https://api.prospeo.io/api/v2/tools/webhook-subscription-update
- Method:
POST
| Parameter | Type | Required | Description |
|---|---|---|---|
webhook_subscription_oid | string | Yes | The subscription to change. |
url | string | No | A new URL, with the same rules as on create. |
all_events | boolean | No | Switch between all events and a chosen list. |
event_types | array of strings | No | Replace the chosen event types. |
enabled | boolean | No | false 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
- URL: https://api.prospeo.io/api/v2/tools/webhook-subscription-delete
- Method:
POST
| Parameter | Type | Required | Description |
|---|---|---|---|
webhook_subscription_oid | string | Yes | The subscription to delete. |
Deliveries stop within 30 seconds.
Receiving events
Each event is a POST to your URL with a JSON body:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Prospeo-Webhooks/1 |
X-Prospeo-Event | The event type, for example DEAL_WON. |
X-Prospeo-Delivery | An opaque id for the event. It is the same every time the same event is sent to the same subscription. |
X-Prospeo-Timestamp | Unix time in seconds when this attempt was signed. |
X-Prospeo-Signature | v1= 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"]
}
}| Property | Type | Description |
|---|---|---|
id | string | The event’s opaque id, the same as X-Prospeo-Delivery. |
type | string | The event type. |
occurred_at | string | When it happened, ISO 8601 in UTC. |
subject | object | The 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. |
data | object | What 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.
Node.js
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
2xxwithin 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-Deliveryto ignore an event you have already handled. - Events from the same record can arrive out of order. Use
occurred_atto order them. - Redirects are not followed.
Event types
These are the event types available today. Call List event types for the current list.
| Event type | Fires when | Family | About |
|---|---|---|---|
CALL_LOGGED | Call logged | call | saved contact |
crm_lifecycle_changed | CRM lifecycle stage changed | crm | saved account, saved contact |
crm_membership_added | Added to a CRM segment | crm | saved account, saved contact |
crm_membership_removed | Removed from a CRM segment | crm | saved account, saved contact |
crm_owner_changed | CRM owner changed | crm | saved account, saved contact |
crm_property_changed | CRM field changed | crm | saved account, saved contact |
crm_record_converted | CRM lead converted | crm | saved account, saved contact |
crm_record_created | CRM record created | crm | saved account, saved contact |
crm_record_deleted | CRM record deleted | crm | saved account, saved contact |
crm_record_linked | CRM record linked to Prospeo | crm | saved account, saved contact |
crm_record_merged | CRM records merged | crm | saved account, saved contact |
ENRICHMENT_COMPLETED | Enrichment completed | data | saved account, saved contact |
IMPORT_COMPLETED | Import completed | data | saved account, saved contact |
DEAL_COMPANY_SET | Deal company set | deal | deal |
DEAL_COMPANY_UNSET | Deal company unset | deal | deal |
DEAL_CONTACT_LINKED | Deal contact linked | deal | deal |
DEAL_CONTACT_UNLINKED | Deal contact unlinked | deal | deal |
DEAL_CREATED | Deal created | deal | deal |
DEAL_FILE_ADDED | Deal file added | deal | deal |
DEAL_LOST | Deal lost | deal | deal |
DEAL_OWNER_CHANGED | Deal owner changed | deal | deal |
DEAL_PIPELINE_MOVED | Deal pipeline moved | deal | deal |
DEAL_REOPENED | Deal reopened | deal | deal |
DEAL_STAGE_CHANGED | Deal stage changed | deal | deal |
DEAL_WON | Deal won | deal | deal |
EMAIL_BOUNCED | Email bounced | saved contact | |
EMAIL_NOT_SENT | Email not sent | saved contact | |
EMAIL_REPLIED | Reply received | saved contact | |
EMAIL_SENT | Email sent | saved contact | |
EMAIL_UNSUBSCRIBED | Email unsubscribed | saved contact | |
FORM_SUBMITTED | Form submitted | form | saved contact |
LIVE_ALERT_CLAIMED | Live alert taken | form | saved contact |
ADDED_TO_LIST | Added to list | list | saved account, saved contact |
REMOVED_FROM_LIST | Removed from list | list | saved account, saved contact |
MAILBOX_AUTO_PAUSED | Mailbox auto paused | mailbox | mailbox |
MAILBOX_HEALTH_CHANGED | Mailbox health changed | mailbox | mailbox |
MEETING_BOOKED | Meeting booked | meeting | meeting, none, saved account, saved contact |
MEETING_CANCELED | Meeting canceled | meeting | meeting, none, saved account, saved contact |
MEETING_NO_SHOW | Meeting no show | meeting | meeting, none, saved account, saved contact |
MEETING_NO_SHOW_UNMARKED | Meeting no-show removed | meeting | meeting, none, saved account, saved contact |
MEETING_RESCHEDULED | Meeting rescheduled | meeting | meeting, none, saved account, saved contact |
ACCOUNT_CREATED | Account created | record | saved account |
COMPANY_OWNER_CHANGED | Account owner changed | record | saved account |
COMPANY_STAGE_CHANGED | Company stage changed | record | saved account |
PERSON_ACCOUNT_LINKED | Contact linked to an account | record | saved contact |
PERSON_ACCOUNT_UNLINKED | Contact unlinked from its account | record | saved contact |
PERSON_JOB_CHANGE_APPLIED | Job change applied | record | saved contact |
PERSON_OWNER_CHANGED | Contact owner changed | record | saved contact |
PERSON_STAGE_CHANGED | Person stage changed | record | saved contact |
RECORD_CREATED | Record created | record | saved contact |
RECORD_UPDATED | Record updated | record | deal, saved account, saved contact |
RECORDING_FAILED | Recording failed | recording | meeting, saved contact |
RECORDING_READY | Recording ready | recording | meeting, saved contact |
REPLY_CATEGORIZED | Reply categorized | reply | saved contact |
REPLY_MACHINE_OUTCOME | Reply machine outcome | reply | saved contact |
REPLY_RULE_FIRED | Reply rule fired | reply | saved contact |
ADDED_TO_SEQUENCE | Added to sequence | sequence | saved contact |
FINISHED_SEQUENCE | Finished sequence | sequence | saved contact |
FIRST_SEQUENCE_STEP | First sequence step | sequence | saved contact |
SEQUENCE_CONTACT_MAILBOX_CHANGED | Contact moved to another mailbox | sequence | saved contact |
SEQUENCE_CONTACT_PAUSED | Sequence contact paused | sequence | saved contact |
SEQUENCE_CONTACT_RESUMED | Sequence contact resumed | sequence | saved contact |
SEQUENCE_PAUSED | Sequence paused | sequence | none |
SEQUENCE_STEP_COMPLETED | Sequence step completed | sequence | saved contact |
TASK_ARCHIVED | Task archived | task | task |
TASK_AUTO_SKIPPED | Task auto-skipped | task | task |
TASK_COMPLETED | Task completed | task | task |
TASK_CREATED | Task created | task | task |
TASK_DUE_DATE_CHANGED | Task due date changed | task | task |
TASK_PRIORITY_CHANGED | Task priority changed | task | task |
TASK_REASSIGNED | Task reassigned | task | task |
If you need further assistance, feel free to reach out via the chat widget on our website.