# Webhooks

URL: /docs/developers/feedback/webhooks

Webhooks let your server react the moment something happens: open a ticket for a new opinion, alert the team about a low rating, or update a dashboard, without polling. Orvelt sends an event when a customer submits, edits, or deletes an opinion, answers a question, comments, verifies a purchase, or subscribes, and when your team, or [Auto priority](/docs/research/how-questions-are-picked#how-auto-priority-learns), changes a project, question, or QR code.

```mermaid
flowchart LR
  accTitle: Webhook delivery
  accDescr: A change in Orvelt sends a POST to your receiver. A 2xx response acknowledges it. Any other response or a timeout is retried with the same event id.
  change["Change in Orvelt"] -->|POST| receiver["Your receiver"]
  receiver -->|2xx| done["Acknowledged"]:::result
  receiver -.->|Other status| change
```

## Create a destination [#create-a-destination]

A destination is the HTTPS URL Orvelt delivers events to, plus the topics it receives. Events cover only projects in your organization, and verification events never include receipt images or extracted evidence.

### In Orvelt Business [#in-orvelt-business]

Open **Integrations → Webhooks → Configure**, enter the endpoint URL, and select the events to send ([step by step](/hc/business/integrations/connect-webhooks)).

![The webhooks dialog contains an HTTPS endpoint URL, a destination ID, selected events, and Save destination.](/hc/screenshots/business-destination-form.png)

### Through the API [#through-the-api]

Webhook configuration is REST-only and requires a [Business session](/docs/developers/authentication#session-only-operations) with Webhooks update access; API keys and SDK methods cannot configure destinations.

- Call [`webhooks.upsert`](/docs/api-reference/endpoints/webhooks/webhooks.upsert) with the receiver's URL and the `topics` it handles. Leave `topics` out to receive every topic. Save the returned `destination.id`.
- To update, call it again with `destinationId`, the required `url` (send the current one even when changing only topics), and the topics. Without `destinationId`, the call creates a second destination.
- Call [`webhooks.portal`](/docs/api-reference/endpoints/webhooks/webhooks.portal) and open the returned `redirectUrl` to see each destination's deliveries, find its signing secret, and retry failed ones. Pass `theme: 'light'` or `theme: 'dark'` to match your tools.

## Events [#events]

Topics are named `<resource>.<past_tense_verb>`, such as `opinion.created` or `verification.verified`: one for each meaningful change to a resource you can read through the API. Every topic and its payload schema is listed under **API reference → Webhooks**, starting with [`opinion.created`](/docs/api-reference/endpoints/webhooks/opinion.created).

### The delivery body [#the-delivery-body]

Every delivery is a JSON `POST` in the [Standard Webhooks](https://www.standardwebhooks.com/) shape:

```json
{
  "id": "01926f3a-8a1e-7c52-9d0b-3c1f6e2a4b10",
  "type": "opinion.created",
  "timestamp": "2026-09-26T14:03:11.482Z",
  "data": { "opinionId": "…", "projectId": "…" }
}
```

- `id` is unique per event and stays the same when a delivery is retried.
- `type` is the topic, and `timestamp` is when the change happened.
- `data` is a snapshot of the resource after the change. It always includes `projectId` for project resources.

### Opinions and answers [#opinions-and-answers]

Opinions and answers are separate resources. A submitted response sends `response.submitted`, then one `answer.created` for each question the customer answered. A public opinion, when the customer writes one, sends `opinion.created`.

### Versions [#versions]

Each topic's reference page shows its payload version. A payload never changes in place: a breaking change increases the version. New optional fields can appear in any version, so read `data` without assuming the field list is closed.

## Build the receiver [#build-the-receiver]

Return any `2xx` status to acknowledge an event. Orvelt retries other statuses and timeouts with the same `id`.

### Receiver checklist [#receiver-checklist]

1. Verify the request signature with the destination's signing secret before trusting the body.
2. Route on `type`, and return `2xx` for topics you ignore so they are not retried.
3. Store or queue the event, then return `2xx`. Do slow work after you respond.
4. Deduplicate on `id`.
5. Log `id`, `type`, and your response status. Never log API keys or delivery links.

### If events stop arriving [#if-events-stop-arriving]

1. Open the portal and confirm the destination URL and topics.
2. Make sure the receiver is reachable over HTTPS from the public internet.
3. Make sure it returns `2xx` as soon as it has stored the event. Any other response counts as a failed delivery.