Skip to content

Developers

Sellcome API and webhooks.

Send new conversations, leads, requests and payments from Sellcome to your own tools, with Zapier or a webhook.

Last updated October 30, 2026

On this page 9 sections
  1. 01What you can build
  2. 02Events
  3. 03Event fields
  4. 04Webhooks
  5. 05Verifying signatures
  6. 06API keys
  7. 07API reference
  8. 08Sellcome on Zapier
  9. 09Help

What you can build

Sellcome’s agent answers customers on your website chat, WhatsApp, Instagram, Messenger, email and text. You can send what happens there to the tools you already use: a CRM, a spreadsheet, Slack or your own system.

  • Zapier. Choose the Sellcome app in Zapier, paste an API key and pick a trigger. No code.
  • Webhooks. Add your address in Sellcome and receive each event as a signed JSON POST.
  • The Sellcome API at https://sellcome.io/api/v1, which the Zapier app uses and you can call too.

Everything is set up in your workspace under Connections → Integrations, by its owner or an admin.

Events

Sellcome sends six events. Test conversations and chats marked as not a customer (newsletters, notifications, suppliers) never send any.

conversation.started
New conversation. A customer starts a conversation on any channel.
lead.captured
New lead. A customer shares an email or phone number.
request.created
New request. Your agent saves a request: a callback, a quote, an order or an appointment.
handoff.requested
Customer asks for a person. A customer wants to talk to someone on your team.
stage.changed
Stage changed. A customer moves to another stage in Sales, won and lost included.
payment.received
Payment received. A customer pays through a payment or cart link your agent sent.

A new conversation and a new lead are sent about three minutes after they happen, so Sellcome can first tell a real customer from an automated message. The others go out within a minute or two.

Event fields

Every event is one flat JSON object with the same fields in the same order, so a spreadsheet or a Zap always finds its columns. Fields that don’t apply are empty strings or null.

id
Unique event id. The same event is never sent twice to one webhook, so you can use it to skip repeats.
event
The event type, such as lead.captured.
event_name
The event’s name as Sellcome shows it, such as “New lead”.
occurred_at
When it happened, in ISO 8601 (UTC).
test
true for a test event sent with Send test or shown in a Zap’s test step.
workspace_id, workspace_name
The Sellcome workspace the event belongs to.
conversation_id, conversation_url
The conversation and a link that opens it in the Sellcome inbox.
channel
Where the customer wrote, such as Website chat, WhatsApp or Email.
customer_name, customer_email, customer_phone
What the customer shared or the channel knows. Empty when unknown.
summary
One line about the conversation, written by the agent for your team.
stage, stage_meaning, previous_stage
The customer’s stage in Sales and what it means: open, ready, won or lost.
amount, currency
The deal amount, from a quoted price, the customer’s budget, your team or a payment.
request_id, request_type, request_summary, request_details, request_due_at
For request.created: the request.
handoff_reason
For handoff.requested: why the customer wants a person.
payment_amount, payment_currency, payment_description
For payment.received: what was paid.
{
  "id": "evt_6f1c2a9d0b7e44c18a3f5d21",
  "event": "lead.captured",
  "event_name": "New lead",
  "occurred_at": "2026-10-30T15:04:00.000Z",
  "test": false,
  "workspace_id": "ws_123",
  "workspace_name": "Bloom Florist",
  "conversation_id": "c_456",
  "conversation_url": "https://sellcome.io/app#inbox/c_456",
  "channel": "Website chat",
  "customer_name": "Jordan Lee",
  "customer_email": "jordan.lee@example.com",
  "customer_phone": "+15125550177",
  "summary": "Wants a dozen peonies delivered Saturday morning.",
  "stage": "Ready to buy",
  "stage_meaning": "ready",
  "previous_stage": "",
  "amount": 89,
  "currency": "USD",
  "request_id": "",
  "request_type": "",
  "request_summary": "",
  "request_details": "",
  "request_due_at": null,
  "handoff_reason": "",
  "payment_amount": null,
  "payment_currency": "",
  "payment_description": ""
}

Webhooks

In Connections → Integrations, click Add next to Webhooks, enter an https address and choose the events. A workspace can have up to 10 webhooks. Send test posts a sample of each chosen event, marked "test": true, and shows what your address answered.

Each delivery is a POST with the event as its body and these headers:

Content-Type
application/json
Sellcome-Event
The event type.
Sellcome-Delivery
The delivery’s id, the same on each retry of it.
Sellcome-Signature
t=<unix seconds>,v1=<hex>, see below.

Answer with any 2xx status within 10 seconds. Redirects aren’t followed. Anything else is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and a day, then given up. A webhook that has failed for three days in a row is paused; saving it again turns it back on. Sellcome keeps the deliveries for 30 days; the latest show under each webhook.

Verifying signatures

Each webhook has its own signing secret (whsec_…): click Show signing secret under the webhook. v1 is the HMAC-SHA256 of the timestamp, a period and the raw body, keyed with that secret, in hex. Compute it over the body exactly as received, compare in constant time, and reject timestamps older than five minutes.

import crypto from 'node:crypto';

// raw: the request body exactly as received; header: the Sellcome-Signature header.
function fromSellcome(raw, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(parts.t + '.' + raw)
    .digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

API keys

Create a key in Connections → Integrations → For developers → Create API key (Connect Zapier makes one for Zapier by itself). It is shown once; Sellcome keeps only its hash. A key opens one workspace’s events, so keep it private, and revoke it there at any time: revoking a key also stops every Zap connected with it. A workspace can have up to 10 keys.

Send the key in the Authorization header (or X-Api-Key). Each key may make 120 requests a minute.

curl https://sellcome.io/api/v1/me \
  -H "Authorization: Bearer sck_…"

Errors are JSON with an error message: 400 for a wrong request, 401 for a missing, wrong or revoked key, 404 for an unknown path and 429 past the rate limit.

API reference

GET /api/v1/me checks a key and names its workspace.

{"workspace_id": "ws_123", "workspace_name": "Bloom Florist"}

POST /api/v1/hooks subscribes an https address to one event, as Zapier does when a Zap is turned on (REST hooks). Body: target_url and event. Answers 201 with the subscription. Up to 50 per workspace.

curl -X POST https://sellcome.io/api/v1/hooks \
  -H "Authorization: Bearer sck_…" -H "Content-Type: application/json" \
  -d '{"target_url": "https://hooks.example.com/sellcome", "event": "lead.captured"}'

{"id": "8c0f…", "event": "lead.captured", "target_url": "https://hooks.example.com/sellcome"}

DELETE /api/v1/hooks/{id} ends a subscription. Answers {"ok": true}, also when it was already gone. If a subscribed address answers 410 Gone, Sellcome ends that subscription by itself.

GET /api/v1/events?event=lead.captured&limit=3 lists the latest events of one type from the last 30 days, newest first (up to 10), in the same shape as deliveries. Before any happened it returns one sample marked "test": true.

Sellcome on Zapier

The Sellcome app on Zapier has one trigger per event: New Conversation, New Lead, New Request, New Handoff Request, Updated Customer Stage and New Payment. Connect it with an API key; the connection is named after your workspace. Each Zap that is on shows under Zaps sending from Sellcome in Connections → Integrations, where Send test runs it with a sample.

Help

Questions or something not working: admin@sellcome.io. Never send an API key or a signing secret by email.

Questions about this page?

Write to us from your workspace, or use the contact page if you don’t have an account yet. A person on our team will reply.