DotIQ webhooks for comments and support tickets

DotIQ webhooks send a signed JSON message to an https URL you choose whenever a comment or support ticket is created, replied to, resolved or changes status, so you can connect Slack, Zapier, Make or your own server.

dotIQ is client feedback and support in one place for agencies and freelancers: clients click on a live web page to leave a pinned comment, and your team turns it into a ticket and replies, all in one dashboard.

Webhooks are set up by an organization admin, or by an app admin for the apps they run. Version v1 of the payload is described here.

Events

Seven events are available. Each webhook listens to the ones you choose.

EventWhen it is sent
comment.createdA new top-level comment was left on a page, by a reviewer or by your team.
comment.repliedSomeone replied in a comment thread.
comment.resolvedA comment thread was marked resolved.
comment.reopenedA resolved comment thread was reopened.
ticket.createdA support ticket was created, from the widget, by email or from a comment.
ticket.repliedA customer or a staff member sent a message on a ticket. Internal notes are never sent.
ticket.status_changedA ticket changed status. The payload carries the new status and the previous one.

Comments that are marked internal, and app ideas, never produce an event.

The message

Every delivery is an HTTP POST with a JSON body. The top level is the same for every event: version, id (the event id), type, created_at, organization_id, app_id and a data object. Ids, status and a url link back to the comment or ticket in DotIQ are always inside data. You choose which of the groups below to add.

Field groupWhat it addsDefault
textThe comment or message text, and the ticket subject.On by default
page_urlThe page the comment was left on.On by default
author_nameThe author's display name.On by default
author_emailThe author's email address. Off by default.Off by default
attachmentsLinks to the screenshot and attachments. Off by default.Off by default
deviceBrowser, operating system and screen size. Off by default.Off by default

Example: a new comment

{
  "version": "v1",
  "id": "evt_0123456789abcdef",
  "type": "comment.created",
  "created_at": "2026-11-14T10:00:00.000Z",
  "organization_id": 12,
  "app_id": 34,
  "data": {
    "comment_id": 101,
    "parent_comment_id": null,
    "status": "open",
    "url": "https://dotiq.io/apps/example/comments/101",
    "text": "The logo is blurry on mobile.",
    "page_url": "https://example.com/about",
    "author_name": "Sam Client"
  }
}

Example: a ticket status change

{
  "version": "v1",
  "id": "evt_0123456789abcdef",
  "type": "ticket.status_changed",
  "created_at": "2026-11-14T10:00:00.000Z",
  "organization_id": 12,
  "app_id": 34,
  "data": {
    "ticket_id": 55,
    "ticket_number": 12,
    "status": "resolved",
    "previous_status": "open",
    "url": "https://dotiq.io/apps/example/support/tickets/12",
    "subject": "Cannot find the invoice",
    "author_name": "Alex Agency"
  }
}

New optional fields and new event types can be added within version v1, so ignore fields you do not know. Removing or renaming a field means a new version, and the old one keeps running for at least 90 days with a notice to affected admins.

Request headers

HeaderMeaning
Content-TypeAlways application/json.
User-AgentdotIQ-Webhooks/1.0
Dotiq-Event-TypeThe event type, for example comment.created.
Dotiq-Event-IdThe event id. The same on every retry and resend.
Dotiq-Delivery-IdUnique for each delivery. A resend gets a new one.
Idempotency-KeyThe event id again, for tools that look for this header.
Dotiq-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>. See below.

Verify the signature

The signature is the HMAC-SHA256 of the timestamp, a dot, and the exact request body, using your webhook's secret as the key, written as lowercase hex. Check it against the raw body text before you parse the JSON, and reject deliveries whose timestamp is more than five minutes old. Your secret starts with whsec_ and is shown once, when you create the webhook or ask for a new one.

Node.js

import crypto from "node:crypto";

// rawBody is the exact request body as text, before any JSON parsing.
function verify(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false; // reject old deliveries
  const expected = crypto.createHmac("sha256", secret).update(timestamp + "." + rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hmac, hashlib, time

# raw_body is the exact request body as bytes, before any JSON parsing.
def verify(secret: str, signature_header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    timestamp = int(parts.get("t", "0"))
    if not timestamp or "v1" not in parts:
        return False
    if abs(time.time() - timestamp) > 300:  # reject old deliveries
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Retries, limits and the delivery log

  • Reply with any 2xx status within 10 seconds to confirm a delivery. The reply body is ignored and redirects are not followed.
  • Network errors, timeouts, 408, 429 and 5xx answers are retried, up to 8 attempts over about 24 hours with growing gaps. Other answers, such as 400 or 404, are final failures.
  • After 20 failed deliveries in a row the webhook is turned off and its creator is emailed. Turn it back on once the endpoint works.
  • Delivery is at least once. De-duplicate with the event id.
  • The URL must use https and must not point to an internal or private address.
  • A message can be up to 256 KB. Up to 5 webhooks per organization and 5 per app.
  • The delivery log shows recent deliveries for 30 days. A failed delivery can be sent again up to 5 times, with the same event id.
  • Press Send test on a webhook to deliver an example event and see your endpoint's answer straight away.

Plans and cost

Webhooks are included on the Pro and Enterprise plans and free during the trial. On Starter and Growth each webhook uses 15 tokens a month for every app it sends for, taken when its first event of the month is sent. A webhook that sends nothing in a month costs nothing.

Zapier and Make

You do not need code to use webhooks. In Zapier, start a Zap with the Webhooks by Zapier trigger and choose Catch Hook. In Make, start a scenario with a Custom webhook. Both give you an https URL: paste it into DotIQ, press Send test so the tool learns the fields, then build the rest of your automation from them, for example a Slack message or a new task.

These tools do not check the signature for you, so treat the URL they give you as a secret. If you need signature checks, receive the webhook on your own server with the code above.

Frequently asked questions

What does a DotIQ webhook send?

A JSON message with a version, a unique event id, the event type, the time, your organization and app ids, and a data object. Ids, status and a link back to DotIQ are always included. Text, page URL and author name are included by default, and author email, screenshot links and device details are included only if you switch them on. Internal notes and ideas are never sent.

How do I know a webhook really came from DotIQ?

Every delivery carries a Dotiq-Signature header: a timestamp and an HMAC-SHA256 signature made from your webhook's secret. Recompute it on your server and compare. The secret is shown once when you create the webhook or ask for a new one.

What happens if my server is down?

DotIQ retries a failed delivery up to 8 times over about 24 hours. Answers that mean the receiver refused the message, such as 400 or 404, are not retried. After 20 failed deliveries in a row the webhook is turned off and its creator gets an email. Failed deliveries stay in the delivery log for 30 days and can be sent again.

Can I receive the same event twice?

Yes, delivery is at least once. Every event has a stable id, sent in the body and in the Idempotency-Key and Dotiq-Event-Id headers. A retry or a resend keeps the same event id, so your receiver can ignore ids it has already handled.

Which plans include webhooks and what do they cost?

Webhooks are included on the Pro and Enterprise plans and free during the trial. On Starter and Growth each webhook uses 15 tokens a month for every app it sends for.

Start collecting clearer feedback

Add the DotIQ widget to your site and let reviewers point at exactly what they mean.

Start free

Last updated