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.
| Event | When it is sent |
|---|---|
comment.created | A new top-level comment was left on a page, by a reviewer or by your team. |
comment.replied | Someone replied in a comment thread. |
comment.resolved | A comment thread was marked resolved. |
comment.reopened | A resolved comment thread was reopened. |
ticket.created | A support ticket was created, from the widget, by email or from a comment. |
ticket.replied | A customer or a staff member sent a message on a ticket. Internal notes are never sent. |
ticket.status_changed | A 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 group | What it adds | Default |
|---|---|---|
text | The comment or message text, and the ticket subject. | On by default |
page_url | The page the comment was left on. | On by default |
author_name | The author's display name. | On by default |
author_email | The author's email address. Off by default. | Off by default |
attachments | Links to the screenshot and attachments. Off by default. | Off by default |
device | Browser, 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
| Header | Meaning |
|---|---|
Content-Type | Always application/json. |
User-Agent | dotIQ-Webhooks/1.0 |
Dotiq-Event-Type | The event type, for example comment.created. |
Dotiq-Event-Id | The event id. The same on every retry and resend. |
Dotiq-Delivery-Id | Unique for each delivery. A resend gets a new one. |
Idempotency-Key | The event id again, for tools that look for this header. |
Dotiq-Signature | t=<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 freeLast updated