Webhooks
Webhooks push events from Pinlyx to your own systems, so you do not have to poll. When something happens (a new contact, an inbound message, a deal that moves), Pinlyx POSTs a signed JSON envelope to every endpoint subscribed to that event.
Every delivery carries an X-Webhook-Signature header with HMAC-SHA256(secret, raw_body). Verify it before you trust the payload. Webhooks are part of the Business plan, with up to 20 endpoints per account.
Register an endpoint
Section titled “Register an endpoint”-
In the Pinlyx app, open Settings › Developers and the Webhooks tab.
-
Click New endpoint and enter the Target URL. It must be a public HTTPS address;
localhost, private and reserved IP addresses are refused. -
Under Subscribed events, pick the events you want, or Subscribe to everything (*). Click Create endpoint.
-
Copy the Signing secret from Save your webhook signing secret. This is the only time the full secret is shown.
-
Open the endpoint’s actions and choose Send test event. A
webhook.testdelivery arrives at your URL and shows up under Show recent deliveries.
You can do the same from code with the /v1/webhooks endpoints (scope webhooks:write), including Rotate secret, which returns a new secret and makes the old one invalid for the next delivery.
Headers on every delivery
Section titled “Headers on every delivery”| Header | Value |
|---|---|
X-Webhook-Signature | sha256=<hex>: lowercase hex HMAC-SHA256 of the raw body, keyed with the endpoint’s secret |
X-Webhook-Event | The event type, for example contact.created |
X-Webhook-Event-Id | The event id. The same on every retry of this delivery |
X-Webhook-Attempt | Attempt number, starting at 1 |
X-Webhook-Timestamp | Unix time (seconds) when this attempt was sent |
Content-Type | application/json; charset=utf-8 |
Envelope
Section titled “Envelope”Every delivery is a JSON object with four keys:
| Field | Description |
|---|---|
event | The event type, same as X-Webhook-Event |
id | The event id, same as X-Webhook-Event-Id |
deliveredAt | ISO 8601 UTC time of this attempt |
data | The event’s payload. Keys inside data are camelCase |
{ "event": "contact.created", "id": "8f14e45fceea167a5a36dedd4bea2543", "deliveredAt": "2026-08-22T09:14:08.1234567Z", "data": { "id": 4821, "userId": 12, "actorUserId": 12, "name": "Ada Lovelace", "username": "adalovelace", "email": "ada@example.com", "phone": "+905551112233", "company": "Analytical Engines", "platform": "telegram", "source": "extension", "stage": "lead", "pipelineId": 3, "pipelineStageId": 11, "createdAt": "2026-08-22T09:14:07Z" }}Record events carry the record’s id and userId (the member who owns the record). Events a person triggered also carry actorUserId (who did it). In a shared workspace the two differ when a teammate edits someone else’s record.
More example payloads
Section titled “More example payloads”{ "id": 551207, "userId": 12, "contactId": 4821, "channel": "social", "platform": "instagram", "direction": "inbound", "accountId": 3, "jobId": null, "externalMessageId": "ig_17924455", "counterparty": "adalovelace", "text": "Sounds good, send the proposal.", "hasMedia": false, "occurredAt": "2026-08-22T09:31:12Z"}{ "id": 341, "userId": 12, "actorUserId": 15, "title": "Analytical Engines - annual", "contactId": 4821, "value": 15000, "currency": "USD", "fromStage": "proposal", "toStage": "negotiation", "probability": 60, "closedAt": null, "changedAt": "2026-08-22T15:00:00Z"}{ "userId": 12, "planId": 4, "planKey": "pro", "planName": "Pro", "previousPlanKey": "starter", "previousPlanName": "Starter", "status": "active", "isActive": true, "startAt": "2026-08-22T00:00:00Z", "endAt": "2026-09-22T00:00:00Z", "origin": "lemonsqueezy_webhook", "changedAt": "2026-08-22T17:00:00Z"}These show the data object only.
Event types
Section titled “Event types”| Event | When it fires |
|---|---|
contact.created | A contact was added, from any source: an inbound message, the panel, the API, a CSV import or the browser extension. source says which. |
contact.updated | A contact’s fields changed. changedFields lists what moved. |
contact.deleted | A contact was archived or deleted. mode says which. |
pipeline.stage_changed | A contact moved between columns on a pipeline board. |
message.sent | An outbound message was sent, on any channel. |
message.received | An inbound message arrived, on any channel: Telegram, the Telegram bot, X, the social inbox, email or live chat. |
sequence.completed | A sequence finished processing all of its targets. |
outreach.step.sent | A step of a multi-channel campaign was sent to a recipient. |
outreach.replied | A campaign recipient replied. |
outreach.completed | A recipient reached the end of a campaign. |
outreach.unsubscribed | A recipient opted out, by link or one-click unsubscribe. |
deal.created | A deal was opened. |
deal.updated | A deal’s title, value, contact, notes or probability changed. Stage moves have their own events. |
deal.stage_changed | A deal moved between stages, with fromStage and toStage. A move to Won or Lost also fires the matching event below. |
deal.won | A deal was closed as won. Fires once, on the transition. |
deal.lost | A deal was closed as lost. |
task.created | A task or reminder was created. |
task.completed | A task reached Done. |
invoice.created | An invoice was drafted. |
invoice.paid | An invoice was marked paid. It arrives together with finance.transaction.created for the income entry. |
finance.transaction.created | A ledger entry was written. origin says by what. |
subscription.changed | Your plan or subscription state changed. origin names what changed it. |
support.ticket.created | A conversation became a support ticket. |
support.ticket.updated | A ticket’s status, priority or owner changed. |
support.ticket.resolved | A ticket was resolved or closed. |
support.ticket.breached | A response-time target was missed. breachKind says which. |
ads.ad.disapproved | An ad in a connected Google Ads account was disapproved and stopped serving. |
ads.budget.exhausted | A campaign’s spend today reached the alert share of its daily budget (95% by default). |
ads.spend.anomaly | Spend is far above the usual pace, or zero on a campaign that normally spends by now. |
ads.billing.problem | Something outside the campaigns stops the account from serving, such as billing. Also fires when it is resolved. |
ads.campaign.status_changed | A campaign’s primary status changed, with the old and new status. |
webhook.test | Sent by Send test event. Safe to ignore. |
GET /v1/webhooks/event-types returns the same list.
Verify the signature
Section titled “Verify the signature”Compute HMAC-SHA256(secret, raw_body), hex-encode it in lowercase, prefix sha256= and compare it with X-Webhook-Signature in constant time.
import crypto from 'node:crypto';
// rawBody: Buffer of the request body, not parsed// sigHeader: value of the X-Webhook-Signature headerfunction verifyWebhook(rawBody, secret, sigHeader) { const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const a = Buffer.from(expected); const b = Buffer.from(sigHeader ?? ''); return a.length === b.length && crypto.timingSafeEqual(a, b);}import hmacimport hashlib
def verify_webhook(raw_body: bytes, secret: str, sig_header: str) -> bool: expected = "sha256=" + hmac.new( secret.encode("utf-8"), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, sig_header or "")<?php// $rawBody = file_get_contents('php://input');// $sigHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';function verifyWebhook(string $rawBody, string $secret, string $sigHeader): bool { $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret); return hash_equals($expected, $sigHeader);}package webhook
import ( "crypto/hmac" "crypto/sha256" "encoding/hex")
// rawBody must be the exact bytes of the request body.func VerifyWebhook(rawBody []byte, secret, sigHeader string) bool { mac := hmac.New(sha256.New, []byte(secret)) mac.Write(rawBody) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(expected), []byte(sigHeader))}The .NET SDK has the same check built in as WebhookSignature.Verify.
Retries and failures
Section titled “Retries and failures”Your receiver has 30 seconds to answer. What happens next depends on the status code:
| Response | Result |
|---|---|
| 2xx | Delivered. The response body is ignored. |
| 408, 429, 5xx, timeout | Retried, up to 8 attempts in total. |
| other 4xx | Not retried. The delivery is marked Gave up straight away, since a 4xx usually means a wrong URL or a receiver that rejects the request. |
Retries wait about 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, then 24 hours between each later attempt, with some random spread. Every attempt carries the same event id, so de-duplicate on it.
After 20 consecutive failed deliveries, across all events, the endpoint is turned off automatically. Fix your receiver, then choose Re-enable endpoint from the endpoint’s actions. Events fired while the endpoint was off are not sent later. A delivery that gave up can be sent again with Retry delivery in the delivery list.
Good to know
Section titled “Good to know”- Answer with a
2xxquickly and do the work afterwards; a slow answer counts as a timeout and is retried. - Make your handler idempotent on the event
id; a retry can arrive after a delivery you already processed. - Rotating a secret takes effect on the next delivery. Update your receiver first.
- Each endpoint has its own secret and its own event subscription.