Quick start
In Settings → Developers, the workspace owner adds a public HTTPS receiver URL and selects events. Save the whsec_… signing secret immediately; it is shown once. Send a test event, then refresh the delivery log. API access must be enabled for your workspace. The feature is off by default. Creating destinations and rotating secrets require fresh 2FA and a 24-hour wait after security changes.
Use your own server or generic webhook tools. These recipes do not require an official Blinkerbot Zapier or Make app. Public REST API supports subscribing and unsubscribing endpoints programmatically.
Events begin with changes observed after subscription; they do not backfill historical contacts. Use GET /v1/contacts for your initial CRM sync.
Envelope and headers
{
"id": "evt_5d4de6c0-3e30-44b8-853f-b3e703da3bf1",
"type": "lead.captured",
"createdAt": "2026-11-12T12:00:00.000Z",
"workspaceId": "workspace_example",
"apiVersion": "2026-11-12",
"data": {
"id": "contact_example",
"name": "Ada",
"phone": "+905550000000",
"email": "ada@example.com",
"tags": ["Qualified"]
}
}Requests are JSON POSTs with Blinkerbot-Event-Id, Blinkerbot-Event-Type and Blinkerbot-Signature. The signature is t=<unix seconds>,v1=<hex HMAC-SHA256>. Sign the UTF-8 bytes of t + "." + rawBody, using the complete literal secret including whsec_. Do not parse and reserialize before verifying.
Reject timestamps more than 300 seconds in the past or future. Compare signatures in constant time. Keep your server clock synchronized. During rotation the header contains two v1 values; accept any valid one. The previous secret remains valid for 24 hours; another rotation is blocked during that overlap.
Node verification
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret, now = Date.now() / 1000) {
const fields = header.split(',');
const ts = fields.filter(f => /^t=/.test(f));
if (ts.length !== 1 || !/^t=\d+$/.test(ts[0])) return false;
const t = Number(ts[0].slice(2));
if (!Number.isSafeInteger(t) || Math.abs(now - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.`).update(rawBody).digest();
return fields.some(f => /^v1=[a-f0-9]{64}$/.test(f) &&
timingSafeEqual(expected, Buffer.from(f.slice(3), 'hex')));
}
// rawBody must be the original request Buffer, before JSON middleware.PHP verification
<?php
function verifyWebhook(string $raw, string $header, string $secret): bool {
$fields = explode(',', $header);
$ts = array_values(array_filter($fields, fn($f) => str_starts_with($f, 't=')));
if (count($ts) !== 1 || !preg_match('/^t=\d+$/D', $ts[0])) return false;
$t = (int) substr($ts[0], 2);
if (abs(time() - $t) > 300) return false;
$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);
foreach ($fields as $field) {
if (preg_match('/^v1=[a-f0-9]{64}$/D', $field) &&
hash_equals($expected, substr($field, 3))) return true;
}
return false;
}
$raw = file_get_contents('php://input');
// Verify before json_decode; read the secret from your secure configuration.Python verification
import hashlib, hmac, re, time
def verify(raw: bytes, header: str, secret: str) -> bool:
fields = header.split(',')
timestamps = [f for f in fields if f.startswith('t=')]
if len(timestamps) != 1 or not re.fullmatch(r't=\d+', timestamps[0]):
return False
t = int(timestamps[0][2:])
if abs(time.time() - t) > 300:
return False
expected = hmac.new(secret.encode(), str(t).encode() + b'.' + raw,
hashlib.sha256).hexdigest()
return any(re.fullmatch(r'v1=[a-f0-9]{64}', f) and
hmac.compare_digest(expected, f[3:]) for f in fields)
# raw is request body bytes, before JSON parsing.Event catalogue
All examples below are the data object inside the envelope. IDs refer only to resources in this workspace. Contact tags are durable contact tags; conversation topics are separate.
Contacts and leads
contact.created: a contact was inserted.contact.updated: name, phone, email or contact-tag membership changed. A message, last-seen update or AI-memory update alone does not emit it.lead.captured: the profile has a non-empty name and phone or email for the first time. It is not emitted again when those values are edited or removed and restored.
{"id":"contact_example","name":"Ada","phone":"+905550000000","email":"ada@example.com","tags":["Qualified"]}Conversations
conversation.created:{"id":"conversation_example","contactId":"contact_example","status":"OPEN","pausedForHuman":false}conversation.handoff_requested:{"id":"conversation_example","contactId":"contact_example","status":"OPEN","pausedForHuman":true}when the assistant/panel pauses the conversation for a person.conversation.closed:{"id":"conversation_example","contactId":"contact_example","status":"CLOSED","pausedForHuman":false}
Messages: explicit opt-in
Select these only when needed; they can generate substantial traffic. message.sent means the stored outbound message reached SENT, DELIVERED or READ, not that an unsent draft was created.
message.received:{"id":"message_example","conversationId":"conversation_example","direction":"INBOUND","contentType":"TEXT","text":"Can I book tomorrow?"}message.sent:{"id":"message_reply","conversationId":"conversation_example","direction":"OUTBOUND","contentType":"TEXT","text":"Which time suits you?"}
Text is bounded to 16,000 characters. Raw provider objects, media credentials and internal metadata are excluded.
Bookings
booking.created is a confirmed booking. booking.cancelled changes status to CANCELLED. booking.rescheduled changes the confirmed start or end time.
{"id":"booking_example","reference":"public_reference","startAt":"2026-11-13T09:00:00Z","endAt":"2026-11-13T09:30:00Z","timezone":"Europe/Istanbul","status":"CONFIRMED","customer":{"name":"Ada","phone":"+905550000000","email":"ada@example.com","contactId":"contact_example"}}For booking.cancelled, status is CANCELLED; for booking.rescheduled, the times are the new times. Customer fields may be null.
Phone calls
call.completed is emitted when a phone-assistant session gets its end timestamp.
{"id":"call_example","startedAt":"2026-11-12T12:00:00Z","endedAt":"2026-11-12T12:02:00Z","durationSeconds":120,"outcome":"COMPLETED","reason":"normal"}There is no recording URL, private transcript, payment data or AI memory. The owner may explicitly enable the masked transcript for an endpoint. If present and unexpired at delivery preparation, it is added as data.transcript; unavailable or oversized transcripts are omitted. Transcript selection is off by default. Payloads are limited to 256 KB. Keep access to receivers restricted and apply your customer privacy notices and retention policy.
Turning transcript inclusion off also removes it from queued retries. Contact erasure removes matching local event snapshots and delivery bodies; manage copies already accepted by your receivers through their own deletion process.
Transcript entries have the form {"role":"user","text":"masked words"} or {"role":"assistant","text":"reply"}. System turns, tool arguments and tool results are excluded.
Comment to DM
comment_delivery.delivered: a comment / DM keyword / story reply rule delivered its content (or handed the DM to the assistant).comment_delivery.lead_collected: the follower typed an e-mail or phone in that journey, for the first time.consentAtis when they answered the consent question.
{"id":"delivery_example","ruleId":"rule_example","ruleName":"Free guide","source":"COMMENT","email":"ada@example.com","phone":null,"follows":"yes","consentAt":"2026-11-14T10:02:00Z","deliveredAt":"2026-11-14T10:02:05Z"}source is COMMENT, DM_KEYWORD or STORY_REPLY; follows is yes, no, unknown or null. The comment text and the follower's Instagram ID are not included.
Retries, idempotency and delivery history
Return any 2xx after durably accepting an event. A successful HTTP response confirms receiver acceptance, not completion of the receiver's CRM actions. Deduplicate using the envelope id (or workspace + id) before applying an action, including when manually resending. Delivery is at least once; receiver timeouts can cause duplicates. Ordering is not guaranteed.
Timeout is 10 seconds. Failed attempts retry after approximately 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, with ±20% jitter, within a 24-hour delivery window. A 410 disables the endpoint immediately. A continuous failure period of 24 hours also disables it and notifies owners through the panel/push notification seam. Any successful attempt resets that failure period. Redirects are failures and are not followed. Private, metadata and link-local destinations are blocked at socket DNS resolution.
Settings → Developers shows the last 50 deliveries from 30 days, status, attempt count, HTTP code and latency. The worker retains at most 1 KB of a response body, without response headers. Resend preserves the event ID/body and starts a new retry run. Send test event queues a synthetic contact.created with data.test: true, regardless of the endpoint's selected event types. Disable/delete endpoints or revoke API keys to stop a connection.
Zapier → HubSpot or Google Sheets
- Create a Zap and choose Webhooks by Zapier → Catch Hook. Copy its URL from the test step; leave the child-key selection empty to retain the event ID.
- Add that URL in Blinkerbot → Settings → Developers; select
lead.capturedand save the secret. - Send a test event in Blinkerbot, then test the Zap trigger.
- Add a HubSpot contact action or Google Sheets row action. Map
data.name,data.phone,data.emailand the envelopeidto your destination fields. - Add deduplication using the envelope
idand turn the Zap on. Check a real lead reaches the CRM.
Catch Hook parses JSON; it does not perform this HMAC verification for you. For verification, place your own verifying receiver in front of Zapier, or use Catch Raw Hook and verify its original body and headers before any CRM action. Treat the catch URL as confidential. Zapier's webhook instructions.
Make → Bitrix24, Kommo or Google Sheets
- Create a scenario with Webhooks → Custom webhook → Add. Save and copy its HTTPS URL.
- Keep Make's optional API-key authentication off for a direct subscription: Blinkerbot sends its signature headers, not
x-make-apikey. Use a verifying proxy if you require that additional header. - Register the URL in Blinkerbot, select
lead.captured, then send a test event so Make learns the fields. - Add your chosen CRM or Google Sheets module and map the
datafields. Store the envelopeidfor deduplication. - Enable the scenario and verify a real lead. If you need HMAC validation, verify raw bytes in a proxy before forwarding to Make.
Make's Custom webhook documentation.
n8n Webhook + HTTP Request
- Add a Webhook node with method POST and a path of your choice. Use a public HTTPS host.
- While testing, select Listen for Test Event and register its Test URL in Blinkerbot. Send a test event.
- Verify HMAC from the original raw body and headers before executing CRM actions; enable raw-body handling in your receiver or use a verifying proxy. Deduplicate the envelope
id. - Add an HTTP Request node for the CRM. To read Blinkerbot, call
https://api.blinkerbot.com/v1/contactswith an Authorization Bearer API key stored as an n8n credential. - Publish the workflow and replace the temporary Blinkerbot endpoint with the node's Production URL. Send another test. Test and production URLs are different.