Webhook events

Delivery

POST <your url>
Content-Type: application/json
X-ParsChat-Signature: <hex hmac-sha256 of raw body, keyed with your secret>
X-ParsChat-Event: message
X-ParsChat-Delivery: dlv_9fK2mQ

Reply 2xx as soon as the event is stored, then do your processing afterwards. A slow handler becomes a timeout, and a timeout becomes a retry.

Verify the signature

Your secret is the Webhook signing secret that the panel shows once, the first time you save your webhook. See Set your webhook.

import hashlib
import hmac
def is_authentic(raw_body: bytes, header_signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_signature)

If your endpoint needs its own authentication

Some partners cannot accept an unauthenticated POST. A bank’s gateway or WAF may require a bearer token or an API key before the request reaches the application at all. Our signature proves the payload came from us, but it does not satisfy your infrastructure’s rule.

You can give us a header set, and we attach it to every delivery, verbatim:

{
  "Authorization": "Bearer <a token you issue to us>",
  "X-Your-Api-Key": "…",
  "X-Client-Id": "…"
}

A plain bearer token works. It is just an Authorization header like any other.

The webhook URL, these headers and your signing secret all live in your panel. Only the return URL comes to us, because it decides where a real customer’s browser is sent mid-signup.

A complete receiver

import hashlib
import hmac
import os
from fastapi import FastAPI, Header, Request, Response
app = FastAPI()
SECRET = os.environ["PARSCHAT_WEBHOOK_SECRET"]
@app.post("/parschat/events")
async def receive(
    request: Request,
    x_parschat_signature: str = Header(default=""),
    x_parschat_event: str = Header(default=""),
    x_parschat_delivery: str = Header(default=""),
) -> Response:
    raw = await request.body()
    expected = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, x_parschat_signature):
        return Response(status_code=401)
    # Store first, process later. A slow handler becomes a timeout,
    # and a timeout becomes a retry of an event you already have.
    enqueue(x_parschat_delivery, x_parschat_event, raw)
    return Response(status_code=200)

Send yourself a test event

Before you wait for real traffic, make us deliver to you on demand:

curl -X POST https://api-chat.parstechai.com/v1/webhooks/test \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "delivery_id": "dlv_4mN6pL",
  "status": "pending"
}

It is a real delivery, not a simulation: signed with your secret, carrying your custom headers, and retried on the same schedule as any other event. So it exercises your signature verification and your firewall rules, not merely whether your host resolves.

Its data carries "test": true so your handler can discard it instead of creating a conversation from it.

if event["data"].get("test"):
    return 200

The call returns 202 as soon as the event is queued — that is not proof your endpoint accepted it. Look the delivery_id up in the delivery log below to see what you actually answered.

Retries

Anything other than a 2xx, including a timeout, is retried with backoff: 6 attempts over about an hour.

Then the delivery is dead-lettered and visible in the panel, so you can see what failed instead of discovering a silent gap.

The delivery log

When an event you expected never arrived, this answers did you actually send it?

curl "https://api-chat.parstechai.com/v1/webhooks/deliveries?status=failed" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "delivery_id": "dlv_7bX4tK",
      "event": "chat",
      "status": "failed",
      "attempt_count": 3,
      "last_status_code": 502,
      "last_error": "upstream returned 502",
      "next_attempt_at": "2026-09-20T11:24:00Z",
      "delivered_at": null,
      "created_at": "2026-09-20T11:08:11Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total_count": 1, "has_more": false }
}

delivery_id is the same value that arrives in the event body, so you can match a log entry to something you did or did not receive.

last_status_code and last_error are the useful pair when debugging: a 502 with next_attempt_at set is transient and self-correcting, while six 500s ending in dead_lettered is a gap you need to reconcile yourself.

Check your configuration

curl https://api-chat.parstechai.com/v1/webhooks \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "url": "https://partner.example/parschat/events",
  "secret_set": true,
  "events": ["message", "chat", "reaction", "is_typing"],
  "updated_at": "2026-09-12T08:15:00Z"
}

Read-only, so you can verify your configuration from code without being able to change it. The secret is never returned, only whether one is set.

The envelope

Every event has the same outer shape:

{
  "schema_version": "1.1.0",
  "event": "message",
  "delivery_id": "dlv_9fK2mQ",
  "occurred_at": "2026-09-20T11:09:02Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": { }
}

schema_version is semver. Fields are added without a major bump, so ignore ones you do not recognise. Nothing is removed or repurposed without a new major version and notice.

Event types

Full payloads for every event: Webhook event reference.

Message types

Attachments arrive as ordinary message events with a non-text type, never as a separate event:

text · voice · image · video · multimedia · document · poll · form · template

Four fields worth explaining

{
  "type": "form",
  "text": null,
  "form_data": [
    { "type": "text", "situation": "question", "key": "Your name", "value": "Sara" },
    { "type": "single_select", "situation": "rate", "key": "Service rating", "value": "excellent" }
  ]
}