Webhooks#

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 and Data processing.

Set up a webhook in the portal#

The fastest way to start receiving claim events:

Open the Karla portal.
Go to Settings → Webhooks.
Add your destination URL.
Select claim events — at minimum claims/created.
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.

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:

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

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:

{
  "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": "[email protected]", "..." : "..." },
    "shipments": [ "..." ]
  }
}

See Claim events 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.
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 or Gorgias integration is simpler — Karla handles authentication and ticket formatting for you.

Where to next#

Zendesk — native Zendesk integration with self-service portal setup.
Gorgias — native Gorgias integration with Help Center embed.
Helpdesk integrations overview — compare connection options.
Webhooks guide — receiver implementation, retries, and signature verification.
Claim events — full event catalog and payload reference.