---
title: "Webhook-slutpunkter"
description: "Hantera flera webhook-URL:er med hemligheter och händelsefilter per slutpunkt."
---

Det endpointbaserade webhook-systemet låter dig registrera **flera**
destinationer per organisation, var och en med sin egen hemlighet, sin egen
status och sin egen prenumeration på en delmängd av händelsetyper. Detta är
den rekommenderade modellen för alla nya integrationer.

Jämför med den [äldre webhooken med en enda URL](/api-reference/organizations#legacy-single-url-webhook),
som behålls för bakåtkompatibilitet men endast stöder en URL per
organisation.

## Slutpunkter

| Metod | Sökväg | Obligatorisk roll | Beskrivning |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Lista slutpunkter |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Skapa en slutpunkt |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Uppdatera etikett / URL / händelser / status |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Ta bort en slutpunkt |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Ersätt signeringshemligheten |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Skicka en signerad testleverans |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Granska senaste leveransresultat för slutpunkter och äldre integrationer |

## Slutpunktsobjekt

```json
{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
```

| Fält | Typ | Beskrivning |
|-------|------|-------------|
| `id` | UUID | Slutpunkts-id |
| `label` | sträng | Visningsnamn, 1–120 tecken |
| `url` | sträng | HTTPS-URL; `http://localhost` tillåts för utveckling |
| `events` | matris av strängar | Prenumererade händelsetyper (se [giltiga värden](#valid-event-types)). En tom matris prenumererar på alla händelser utom händelser per tur som endast kan prenumereras explicit på (`telephony.turn` / `web.turn`) |
| `status` | sträng | `active`, `disabled` (pausad manuellt) eller `failing` (ställs in automatiskt när en leverans förbrukar sitt återförsöksschema på 24 timmar utan en enda 2xx-respons) |
| `agent_id` | heltal \| null | Röstagenten som denna slutpunkt är begränsad till; `null` innebär organisationsomfattande |
| `agent_name` | sträng \| null | Namnet på den begränsade röstagenten, eller `null` för en organisationsomfattande slutpunkt |
| `secret_hint` | sträng | De första 4 och sista 4 tecknen i signeringshemligheten med en ellips (`a1b2…9f0e`) — tillräckligt för att jämföra med hemligheten du sparat lokalt utan att exponera hela värdet |
| `paused_at` | tidsstämpel \| null | När ThunderPhone satte slutpunkten till `failing`. `null` medan den är `active` eller `disabled` |
| `pause_last_error` | sträng | Det senaste leveransfelet när slutpunkten pausades, till exempel `HTTP 503: Service Unavailable`. Tomt om den inte är `failing` |
| `pause_undelivered_count` | heltal \| null | Händelser som inte har levererats sedan slutpunktens senaste lyckade leverans, räknade när den pausades |
| `created_at`, `updated_at` | tidsstämpel | |

<Note>
  Endpointens fullständiga `secret` returneras **endast en gång** vid skapandet och
  aldrig igen. Förvara den säkert — om du förlorar den,
  [rotera den](#rotate-the-signing-secret) för att få en ny.
</Note>

### Giltiga händelsetyper

`events` valideras mot exakt denna uppsättning — värden utanför listan
returnerar `400`. Se [Händelsekatalog](/sv/webhooks/events) för varje typs
payload-format.

- `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `sms.sent`, `sms.failed`
- `sms.received` (reserverad; ännu inte skickad)
- `call.graded`, `call.data_extracted`, `call.transfer_completed`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`

`issue.escalated` har inget agentkontext och levereras endast till
organisationsomfattande slutpunkter.

`voice.ready` och `voice.failed` kan inte väljas uttryckligen. Skapa en
organisationsomfattande slutpunkt med `events: []` för att ta emot dem. En tom
händelselista tar emot alla händelser som stöds utom `telephony.turn` och
`web.turn`, som måste väljas uttryckligen.

### Slutpunktsstatusar

- `active` — leveranser fungerar normalt.
- `disabled` — pausad manuellt via `PATCH`. Inga förfrågningar skickas. Vi
  ändrar aldrig statusen för en `disabled`-endpoint; att ändra tillbaka den till
  `active` är alltid ditt beslut.
- `failing` — ställs in automatiskt när en leverans till endpointen förbrukar
  hela sitt återförsöksschema (8 försök under 24 timmar) utan att någonsin få en 2xx. En felande endpoint tar inte emot någon ytterligare trafik.
  Vi skickar e-post till organisationens ägare och administratörer när detta händer, och
  instrumentpanelen visar den pausade endpointen med en knapp för att återaktivera.
  När endpointen har åtgärdats, ändra dess status med `PATCH` tillbaka till `active`;
  leveranser vars återförsöksschema ännu inte har löpt ut återupptas där de
  slutade.

---

## Lista slutpunkter

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returnerar en array med [slutpunktsobjekt](#endpoint-object).
Ange `?agent_id=42` för att endast returnera slutpunkter som är begränsade till den agenten.

### Agentspecifika slutpunkter

Organisationsomfattande slutpunkter tar emot varje matchande händelse. En slutpunkt med
`agent_id` tar endast emot matchande händelser för samtal som hanteras av den agenten;
händelser utan agentkontext, exempelvis `alert.triggered`, når den aldrig. Du kan
också skapa och hantera dessa slutpunkter från avsnittet
**Webhooks** i agentbyggaren.

---

## Skapa en slutpunkt

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

```python Python
result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]
```
</CodeGroup>

### Begärandefält

| Fält | Typ | Obligatoriskt | Beskrivning |
|-------|------|----------|-------------|
| `label` | string | ja | 1–120 tecken |
| `url` | string | ja | HTTPS-URL (`http` tillåts endast för `localhost` / `127.0.0.1`) |
| `events` | array | nej | Tomt/utelämnat prenumererar på alla händelser utom `telephony.turn` / `web.turn`, som kräver en uttrycklig prenumeration. Måste använda värdena som anges i [Giltiga händelsetyper](#valid-event-types); dubbletter tas bort |
| `agent_id` | integer \| null | nej | Begränsa leveransen till en agent i den här organisationen; utelämna eller använd `null` för en organisationsomfattande slutpunkt |

Returnerar `201 Created` med [slutpunktsobjektet](#endpoint-object) samt
ett extra `secret`-fält på toppnivå som innehåller den råa signeringsnyckeln — en
hexadecimala sträng med 48 tecken:

```json
{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}
```

<Warning>
  `secret` returneras **endast när slutpunkten skapas**. Efterföljande `GET`-svar
  innehåller endast `secret_hint`. Kopiera hela värdet till din
  hemlighetshanterare innan du stänger svaret.
</Warning>

---

## Uppdatera en slutpunkt

<CodeGroup>
```bash cURL
curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'
```
</CodeGroup>

| Fält | Typ | Beskrivning |
|-------|------|-------------|
| `label` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` eller `disabled`. Ange `active` för att återaktivera en slutpunkt som servern har markerat som `failing` |
| `agent_id` | integer \| null | Ange ett agent-id för att begränsa slutpunkten, eller `null` för att göra den organisationsomfattande |

Returnerar `200 OK` med det uppdaterade [slutpunktsobjektet](#endpoint-object).

---

## Rotera signeringshemligheten

Ersätt en slutpunkts signeringshemlighet, till exempel om den har gått förlorad eller
kan ha läckt. För en agentspecifik slutpunkt kan du även använda
instrumentpanelen: öppna agentens avsnitt **Webhooks** och välj
**Återskapa hemlighet** på slutpunkten. Organisationsomfattande slutpunkter
roteras via API:t.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
</CodeGroup>

| Fält | Typ | Obligatoriskt | Beskrivning |
|-------|------|----------|-------------|
| `include_copies` | boolesk | nej | Standardvärdet är `true`. Ger även den nya hemligheten till organisationens andra slutpunkter som har samma URL och samma aktuella hemlighet, till exempel kopior av denna slutpunkt på andra agenter, så att en mottagare fortsätter att verifiera med en och samma hemlighet |

Returnerar `200 OK`:

```json
{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}
```

| Fält | Typ | Beskrivning |
|-------|------|-------------|
| `endpoint` | objekt | [Endpoint-objektet](#endpoint-object) med dess nya `secret_hint` |
| `secret` | sträng | Den nya signeringshemligheten. Returneras endast i detta svar |
| `rotated_endpoint_ids` | matris med UUID | Varje slutpunkt som nu använder den nya hemligheten |

<Warning>
  Den gamla hemligheten slutar användas omedelbart: nästa leverans,
  inklusive återförsök, signeras med den nya. Tills din mottagare har
  den nya hemligheten misslyckas leveranser med dess signaturkontroll; om den svarar
  på dem med en status som inte är 2xx görs nya försök enligt det vanliga schemat på
  24 h, så uppdatera mottagaren snarast. Om din mottagare rullas ut
  stegvis bör den acceptera båda hemligheterna under utrullningen — SDK:ns
  verifieringshjälpare tar emot en lista med hemligheter (se
  [Verifiera webhook-signaturer](/sv/guides/verify-webhook-signatures)).
</Warning>

---

## Skicka en testleverans

Skicka en syntetisk `webhook.test`-händelse till en endpoint via den vanliga
leveransprocessen, inklusive kanonisk JSON-serialisering, båda
signaturhuvudena, leveransloggning och hantering av återförsök.
Testet riktas mot den valda endpointen oavsett dess `events`-filter.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Slutpunkten tar emot ett kuvert som detta:

```json
{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}
```

API:et returnerar `200 OK` efter det första försöket, även om destinationen
returnerar ett fel. Kontrollera `success`, `status`, `response_code` och `error`
för leveransresultatet:

```json
{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}
```

`webhook.test` är syntetisk och kan inte läggas till i en slutpunkts `events`-
prenumeration. Om det första försöket misslyckas försöker ThunderPhone igen en gång
ungefär en minut senare och stoppar sedan; leveransen visas då med `status: "failed"`
under [Felsök leveranser](#debug-deliveries). En testleverans markerar aldrig
slutpunkten som `failing`.

Om du vill konfigurera en utlösare mot en verklig händelseform kan du skicka ett valfritt
`event_type`. Leveransen är fortfarande syntetisk och innehåller `"sample": true`;
samtalsrelaterade exempel använder `call_id: 0` och `agent_id: 0`.

```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'
```

`event_type` accepterar alla värden från [Giltiga händelsetyper](#valid-event-types).
Om du utelämnar det behålls det generella `webhook.test`-beteendet.

---

## Ta bort en slutpunkt

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Returnerar `204 No Content`. Leverans till URL:en stoppas omedelbart;
pågående återförsök avbryts.

---

## Felsök leveranser

Innan du drar slutsatsen att en webhook inte skickades bör du kontrollera
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Den visar senaste försök från båda webhook-systemen, inklusive samtals-id,
URL-ursprung, HTTP-status, antal försök, vitlistad felkategori och tid för nästa
återförsök. Den returnerar aldrig händelsens nyttolast, transkription, lagrad feltext,
svarstext eller URL-sökväg.

Du kan även se samma senaste historik i **Agenter → välj en agent → Webhooks →
Senaste leveranser**. Rader visar slutpunktens etikett och det URL-ursprung som användes vid det senaste
försöket. Detta är driftstatus snarare än en oföränderlig granskningslogg: om du tar bort en slutpunkt
tas även dess leveransrader bort.

För en n8n-`404` ska du först bekräfta att arbetsflödet är aktivt, accepterar `POST` och använder
produktionswebhookens URL i stället för test-URL:en. En `401` eller `403` pekar på
autentisering eller signaturvalidering; tidsgränser pekar på fördröjning
eller tillgänglighet hos destinationen; TLS-fel pekar på certifikatkedjan, värdnamnet eller utgångsdatumet.

---

## Relaterat

<CardGroup cols={2}>
  <Card title="Händelsekatalog" icon="list" href="/sv/webhooks/events">
    Den fullständiga listan över `events`-värden som du kan prenumerera på.
  </Card>
  <Card title="Översikt över webhooks" icon="bolt" href="/sv/webhooks/overview">
    Signaturverifiering och leveranssemantik.
  </Card>
</CardGroup>