# Webhooks

Source: https://gokarla.io/docs/guides/resolve/integrations/webhooks

# Webhooks

:::info

Webhooks let you connect Resolve to **any** helpdesk or internal tool. Karla
POSTs a structured claim event to your endpoint the moment a customer submits
— you (or a middleware layer) translate that payload into a ticket.

:::

This is the most flexible integration path. Use it when your helpdesk is not
yet supported as a native integration, when you need a custom ticket format,
or when you want to fan out the same claim to multiple systems.

## Claim events

Resolve emits two claim events:

| Event         | Ref              | When                                 |
| ------------- | ---------------- | ------------------------------------ |
| Claim created | `claims/created` | Customer submits a new Resolve claim |
| Claim updated | `claims/updated` | Claim status or details change       |

For the full payload shape — including `event_data`, order context, shipment
data, and photo URLs — see [Claim events](/docs/platform/events/claims) and
[Data processing](../data-processing).

## Set up a webhook in the portal

The fastest way to start receiving claim events:

1. Open the [Karla portal](https://portal.gokarla.io/).
2. Go to **Settings → Webhooks**.
3. Add your destination URL.
4. Select claim events — at minimum `claims/created`.
5. Save.

Karla starts delivering events immediately. Your endpoint must accept HTTPS
POST requests with a valid TLS certificate.

For programmatic setup, signature verification, retries, and receiver
implementation details, see the general
[Webhooks guide](/docs/guides/notify/webhooks).

## Map the payload to your helpdesk

Karla sends the raw structured claim — it does not shape the payload for your
specific helpdesk. That is by design: you control how the ticket looks.

A typical receiver flow:

1. **Receive** the `claims/created` webhook from Karla.
2. **Extract** customer email, reason, affected items, and photo URLs from
   `event_data` and `context`.
3. **Create a ticket** in your helpdesk via its API — Zendesk, Freshdesk,
   Intercom, a custom internal tool, or anything with an HTTP API.
4. **Attach evidence** — download photo URLs from the payload and attach them
   to the ticket.

:::tip Middleware connectors
If you do not want to build a receiver yourself, tools like Zapier, Make, or
n8n can accept Karla webhooks and call your helpdesk API. Point the webhook
at the connector and map fields visually.
:::

## Example: minimal claim payload

The webhook body follows the standard Karla event envelope. The claim-specific
fields live in `event_data`:

```jsx title="claims/created event_data (abbreviated)"
{
  "ref": "claims/created",
  "event_group": "claim_created",
  "event_data": {
    "claim_id": "38fdc365-7de9-4313-afbd-0ed23717c5e0",
    "reason": "partial_damage",
    "resolution_preference": "refund",
    "description": "Package was damaged on the right side",
    "selected_items": [
      {
        "sku": "ABCD3",
        "title": "Product Title",
        "quantity": 1
      }
    ],
    "image_urls": [
      "https://cdn.gokarla.io/.../claim"
    ]
  },
  "context": {
    "order": { "order_number": "0000001", "..." : "..." },
    "customer": { "email": "customer@example.com", "..." : "..." },
    "shipments": [ "..." ]
  }
}
```

See [Claim events](/docs/platform/events/claims) for the complete payload with
full order and shipment context.

## Security

- All webhook traffic uses **HTTPS** with TLS 1.2 or higher.
- Verify webhook signatures using the secret configured in the portal — see
  [Webhooks → Verifying signatures](/docs/guides/notify/webhooks).
- **Static IP egress** is available as a premium add-on if your receiver sits
  behind a firewall and you need to allow-list a fixed source. Talk to your
  account manager if you need this.

## Native integrations vs webhooks

|                   | Native integration             | Webhooks                                   |
| ----------------- | ------------------------------ | ------------------------------------------ |
| Setup             | Portal — credentials only      | Portal or API — endpoint + event selection |
| Ticket formatting | Handled by Karla               | You (or your middleware)                   |
| Helpdesk support  | Zendesk, Gorgias (more coming) | Any tool with an HTTP API                  |
| Best for          | Standard ticket creation       | Custom shapes, multi-destination fan-out   |

If Zendesk or Gorgias is your helpdesk, the native
[Zendesk](./zendesk) or [Gorgias](./gorgias) integration is simpler — Karla
handles authentication and ticket formatting for you.

## Where to next

- [Zendesk](./zendesk) — native Zendesk integration with self-service portal
  setup.
- [Gorgias](./gorgias) — native Gorgias integration with Help Center embed.
- [Helpdesk integrations overview](./overview) — compare connection options.
- [Webhooks guide](/docs/guides/notify/webhooks) — receiver implementation,
  retries, and signature verification.
- [Claim events](/docs/platform/events/claims) — full event catalog and
  payload reference.