Webhooks

Webhooks let your team receive automatic real-time notifications on your own server when events happen in Pliic — such as a new suggestion submitted or a status change on a ticket.

Webhooks are available on the Starter plan (up to 3 endpoints) and Pro plan (unlimited). The Free plan does not include this feature. Only members with the Admin or Owner role can manage webhooks.

Creating an endpoint

1. Go to Settings → Webhooks
2. Click Add endpoint
3. Fill in the fields:
   • Name — an internal label for the endpoint
   • URL — a public HTTPS address that will receive the notifications
   • Events — select which events should trigger this endpoint
4. Click Create

After creating, a signing secret (whsec_…) is shown only once. Copy and store it securely — it cannot be retrieved later.

Available events

Event	Description
suggestion.created	A new suggestion was submitted.
suggestion.status_changed	A suggestion’s status was changed.
suggestion.commented	A comment was added to a suggestion.
ticket.created	A new ticket was opened.
ticket.status_changed	A ticket’s status was changed.
ticket.replied	A reply was added to a ticket.

Payload format

Each delivery is a POST request with Content-Type: application/json in the following format:

{
  "id": "018e1234-5678-7abc-def0-123456789abc",
  "event": "suggestion.created",
  "created_at": "2024-01-15T14:30:00Z",
  "data": { ... }
}

Field	Type	Description
id	string (UUID)	Unique identifier for this delivery.
event	string	Name of the event that fired.
created_at	string (ISO 8601)	Date and time of the event in UTC.
data	object	Event-specific payload data.

Request headers

Each delivery includes the following HTTP headers:

Header	Description
X-Pliic-Signature	HMAC-SHA256 signature of the raw request body.
X-Pliic-Event	Event name (e.g. suggestion.created).
X-Pliic-Delivery	Unique UUID for this delivery.

Verifying the signature

Verifying the signature confirms that the request was sent by Pliic and that the payload was not tampered with in transit.

Compute HMAC-SHA256(secret, raw_body) and compare it to the X-Pliic-Signature header value using constant-time comparison.

PHP:

function verifySignature(string $secret, string $rawBody, string $signature): bool
{
    $expected = hash_hmac('sha256', $rawBody, $secret);

    return hash_equals($expected, $signature);
}

Node.js:

const crypto = require('crypto');

function verifySignature(secret, rawBody, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Caution

Always use the raw body of the request when computing the signature — never the already-parsed JSON object. Parsing and re-serializing JSON can change field order and invalidate the check.

Delivery and retries

If your server returns a non-2xx status or the connection times out, Pliic will automatically retry with exponential backoff:

Attempt	Approximate delay
1st (retry)	5 minutes
2nd	15 minutes
3rd	45 minutes
4th	135 minutes
5th	405 minutes (~6.75 hours)

After 5 failed attempts the delivery is abandoned.

The full history of each delivery — status, response code, and number of attempts — is available on the endpoint’s detail page.

Testing your endpoint

On the endpoint detail page, click Send test. Pliic will deliver a webhook.ping event so you can verify that your server is receiving requests correctly before activating real events.

Security

• Only public HTTPS URLs are accepted. Internal, private-network, or localhost addresses are rejected.
• The TLS certificate of the destination server is always verified.
• Never share the signing secret or include it in public code or logs.