Webhooks allow your application to receive real-time notifications about specific events happening in our platform — such as new messages or conversation updates.You can configure webhooks directly from your Qpien account to subscribe to the events you want to be notified about.
How It Works#
1.
Customer creates a webhook with endpoint they provided(https://example.com/webhook) and subscribes to an event or events (NEW_INCOMING_MESSAGE)
2.
Our system generates an HMAC_SECRET and displays it once.
3.
When a new message arrives, we POST the event payload to your endpoint.
4.
Your system verifies the signature using your stored HMAC secret.
5.
If verification passes and your endpoint returns 200 OK, the webhook is marked as successful.
6.
Otherwise, retries are triggered based on exponential backoff.
| Field | Description | Example |
|---|
| endpointUrl | The HTTPS endpoint on your server where event notifications will be sent. | https://yourdomain.com/webhook |
| events | The list of event types you want to subscribe to. | ["NEW_INCOMING_MESSAGE", "JOIN_CONVERSATION"] |
| status | Indicates whether the webhook is currently active. A disabled webhook will not receive any events. | ACTIVE or DISABLED |
| secret | The HMAC secret key used to verify webhook signatures. This is only shown once when the webhook is created — make sure to store it securely. | 9f8d1b91e23a4a0f8f4b1c8d7b2f19e1 |
After creating the webhook, the API will respond with your unique HMAC secret.Important: This secret is visible only once — please store it safely, as it will be hidden afterward..
Security & Signature Verification#
Every webhook event we send includes an HMAC SHA-256 signature in the request headers, so you can confirm the request genuinely originated from our system.Every webhook event request includes the header:X-Qpien-Signature: <hexadecimal-signature>Signature Generation (our side)#
We generate the signature as:HMAC_SHA256(secret, JSON.stringify(payload))Example Verification (your side)#
Here’s how you can verify the webhook payload in your app✅ Tip: Always verify signatures to prevent unauthorized or spoofed webhook requests.Delivery & Retry Mechanism#
When an event occurs, we send a POST request to your configured endpointUrl with the event payload.Expected Response#
Your endpoint must respond with an HTTP 200 OK status to confirm successful receipt.
Any other response code (4xx/5xx) or timeout will be considered a failed attempt.Retry Logic#
We automatically retry failed webhook deliveries using exponential backoff:| Attempt | Delay Before Retry |
|---|
| 1 | 1 minute |
| 2 | 2 minutes |
| 3 | 4 minutes |
| 4 | 8 minutes |
| 5 | 16 minutes |
| 6 | 64 minutes |
| 7 | 128 minutes (~2 hours total) |
After the 7th failed attempt:The webhook status is set to disabled.
No further events will be sent.
You can re-enable the webhook manually from your Qpien account once the issue is fixed on your endpoint.
Webhook Events#
Each webhook event will be sent as a POST request to your configured endpointUrl with a JSON body containing the event data.All webhook payloads share a common envelope:NEW_INCOMING_MESSAGE#
Triggered when a new message is received from a customer.NEW_OUTGOING_MESSAGE#
Triggered when a new message is sent from your team to the customer.JOIN_CONVERSATION#
Triggered when an agent joins a conversation.CLOSE_CONVERSATION#
Triggered when a conversation is closed.REOPEN_CONVERSATION#
Triggered when a previously closed conversation is reopened.UPDATE_USER#
Triggered when an agent status is changedBest Practices#
📌 Always verify X-Qpien-Signature before processing payloads..📌 Make sure your webhook endpoint responds within 5 seconds to avoid timeouts.📌 Use HTTPS for your endpoint URLs — HTTP is not allowed.📌 Re-enable disabled webhooks from your account once your endpoint is stable.. 