Skip to content

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.

  1. In the Pinlyx app, open Settings › Developers and the Webhooks tab.

  2. Click New endpoint and enter the Target URL. It must be a public HTTPS address; localhost, private and reserved IP addresses are refused.

  3. Under Subscribed events, pick the events you want, or Subscribe to everything (*). Click Create endpoint.

  4. Copy the Signing secret from Save your webhook signing secret. This is the only time the full secret is shown.

  5. Open the endpoint’s actions and choose Send test event. A webhook.test delivery 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.

HeaderValue
X-Webhook-Signaturesha256=<hex>: lowercase hex HMAC-SHA256 of the raw body, keyed with the endpoint’s secret
X-Webhook-EventThe event type, for example contact.created
X-Webhook-Event-IdThe event id. The same on every retry of this delivery
X-Webhook-AttemptAttempt number, starting at 1
X-Webhook-TimestampUnix time (seconds) when this attempt was sent
Content-Typeapplication/json; charset=utf-8

Every delivery is a JSON object with four keys:

FieldDescription
eventThe event type, same as X-Webhook-Event
idThe event id, same as X-Webhook-Event-Id
deliveredAtISO 8601 UTC time of this attempt
dataThe 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.

{
"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"
}

These show the data object only.

EventWhen it fires
contact.createdA contact was added, from any source: an inbound message, the panel, the API, a CSV import or the browser extension. source says which.
contact.updatedA contact’s fields changed. changedFields lists what moved.
contact.deletedA contact was archived or deleted. mode says which.
pipeline.stage_changedA contact moved between columns on a pipeline board.
message.sentAn outbound message was sent, on any channel.
message.receivedAn inbound message arrived, on any channel: Telegram, the Telegram bot, X, the social inbox, email or live chat.
sequence.completedA sequence finished processing all of its targets.
outreach.step.sentA step of a multi-channel campaign was sent to a recipient.
outreach.repliedA campaign recipient replied.
outreach.completedA recipient reached the end of a campaign.
outreach.unsubscribedA recipient opted out, by link or one-click unsubscribe.
deal.createdA deal was opened.
deal.updatedA deal’s title, value, contact, notes or probability changed. Stage moves have their own events.
deal.stage_changedA deal moved between stages, with fromStage and toStage. A move to Won or Lost also fires the matching event below.
deal.wonA deal was closed as won. Fires once, on the transition.
deal.lostA deal was closed as lost.
task.createdA task or reminder was created.
task.completedA task reached Done.
invoice.createdAn invoice was drafted.
invoice.paidAn invoice was marked paid. It arrives together with finance.transaction.created for the income entry.
finance.transaction.createdA ledger entry was written. origin says by what.
subscription.changedYour plan or subscription state changed. origin names what changed it.
support.ticket.createdA conversation became a support ticket.
support.ticket.updatedA ticket’s status, priority or owner changed.
support.ticket.resolvedA ticket was resolved or closed.
support.ticket.breachedA response-time target was missed. breachKind says which.
ads.ad.disapprovedAn ad in a connected Google Ads account was disapproved and stopped serving.
ads.budget.exhaustedA campaign’s spend today reached the alert share of its daily budget (95% by default).
ads.spend.anomalySpend is far above the usual pace, or zero on a campaign that normally spends by now.
ads.billing.problemSomething outside the campaigns stops the account from serving, such as billing. Also fires when it is resolved.
ads.campaign.status_changedA campaign’s primary status changed, with the old and new status.
webhook.testSent by Send test event. Safe to ignore.

GET /v1/webhooks/event-types returns the same list.

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 header
function 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);
}

The .NET SDK has the same check built in as WebhookSignature.Verify.

Your receiver has 30 seconds to answer. What happens next depends on the status code:

ResponseResult
2xxDelivered. The response body is ignored.
408, 429, 5xx, timeoutRetried, up to 8 attempts in total.
other 4xxNot 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.

  • Answer with a 2xx quickly 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.