Webhooks

Webhooks let your system react when something changes in Qwoty. When a subscribed event occurs, Qwoty sends an HTTP POST with a small JSON payload to the endpoint URL you configured. The payload tells you what changed; call the API to read the current state of the object.

Create a webhook

Webhooks are configured in the app, not through the API.

Open the webhook settings

Go to Settings › Developer › Webhook and click New.

Fill in the form

Name (required) and Description (optional) help you recognize the webhook.
Endpoint URL (required): the public URL that receives the POST requests.
Object (required): the type of object to watch: Quote, Product, Customer or Customer segment. Order and Contract are listed as “coming soon” and cannot be selected yet.
Event (required): one or more events for that object (New, Update, Delete, and Validation for quotes).
Secret (optional): a value of your choice that Qwoty includes in every payload so you can check that the call comes from Qwoty.

Save

Click Save. The webhook list shows a Last delivery column (Delivered, Failed or Never triggered) to help you debug your endpoint.

New webhook form in Settings › Developer › Webhook

One webhook watches one object. To receive events for several objects, create one webhook per object (they can point to the same endpoint URL). For a step-by-step guide in the app, see Webhooks.

Events

The event name sent in the payload is <object>.<event>.

Object	Events	Sent when
Quote	`quote.new`, `quote.update`, `quote.delete`	A quote is created, changed (content, settings, status…) or deleted
Quote	`quote.validation`	A quote becomes Accepted (signed by the customer, or marked as accepted)
Product	`product.new`, `product.update`, `product.delete`	A product is created, changed or deleted
Customer	`customer.new`, `customer.update`, `customer.delete`	A customer is created, changed or deleted
Customer segment	`customer_segment.new`, `customer_segment.update`, `customer_segment.delete`	A customer segment is created, changed or deleted

Events are sent whether the change was made in the app or through the API.

Payload

Every delivery is a POST with Content-Type: application/json:

{
  "event": "quote.update",
  "workspace_id": "990e8400-e29b-41d4-a716-446655440004",
  "associated_object_id": "550e8400-e29b-41d4-a716-446655440000",
  "associated_object_type": "quote",
  "secret": "the-secret-you-entered"
}

Field	Description
`event`	Event name, for example `quote.update`
`workspace_id`	Workspace where the event happened (UUID)
`associated_object_id`	ID of the changed object (UUID). For `product.` events, it is the ID of the product (variant), usable with Get Product. For `quote.` events, use it with Get Quote.
`associated_object_type`	`quote`, `product`, `customer` or `customer_segment`
`secret`	The Secret configured on the webhook. Omitted when no secret is set.
`data`	Extra data, present only for some events

Secure your endpoint

Qwoty does not sign webhook requests: there is no signature or timestamp header. To check that a call comes from Qwoty:

Set a long random Secret on the webhook.
In your endpoint, compare the secret field of the JSON body with your stored value, and reject the request (for example with 401) if they differ.
Only expose your endpoint over HTTPS so the secret is encrypted in transit.

Node.js (Express)

app.post('/qwoty/webhook', express.json(), (req, res) => {
  if (req.body.secret !== process.env.QWOTY_WEBHOOK_SECRET) {
    return res.sendStatus(401)
  }
  res.sendStatus(200) // answer first
  queue.push(req.body) // then process asynchronously
})

Delivery

Qwoty makes one attempt per event and endpoint. There are no retries: a failed delivery is not sent again.
The request times out after 10 seconds. Any non-2xx status, timeout or network error counts as a failure and is shown as Failed in the Last delivery column.
Order is not guaranteed between events.

Best practices

Answer fast. Return a 2xx right away and do the processing asynchronously, well within the 10-second timeout.
Fetch the latest state. The payload only identifies the object: read it with the API (for example Get Quote or Get Customer) before acting on it.
Be idempotent. The same object can trigger several update events in a row; make sure processing the same event twice is harmless.
Reconcile periodically. Because failed deliveries are not retried, run a periodic sync with the list endpoints (for example List Quotes) if you cannot afford to miss an event.

Getting started

Core concepts

Resources

Compliance

Policies

Create a webhook

Events

Payload

Secure your endpoint

Delivery

Best practices

​Create a webhook

​Events

​Payload

​Secure your endpoint

​Delivery

​Best practices

Create a webhook

Events

Payload

Secure your endpoint

Delivery

Best practices