Webhooks

Met webhooks ontvang je realtime meldingen wanneer er iets gebeurt in je LabelGrid-account. Gebruik webhooks om workflows te automatiseren en aan externe systemen te koppelen.

Opmerking

Webhooks vereisen dat API-toegang is ingeschakeld op je account. Neem contact op met support als je deze functie nodig hebt.

Voor ontwikkelaars: Je kunt webhooks ook programmatisch beheren via de API. Zie de LabelGrid API-documentatie voor endpoints en voorbeelden.

Hoe webhooks werken

1. Je stelt een webhook in - Geef een URL op en de gebeurtenissen waarop je wilt reageren
2. Er gebeurt iets - Bijvoorbeeld: een release wordt geleverd aan een winkel
3. LabelGrid stuurt een POST-verzoek - Je server ontvangt de gegevens van de gebeurtenis
4. Je systeem verwerkt het - Automatiseer workflows op basis van de gebeurtenis

---

Webhooks openen

1. Klik rechtsboven op je profielpictogram
2. Kies Webhooks in het uitklapmenu

---

Een webhook aanmaken

1. Klik op Create Webhook
2. Voer een Naam in om deze webhook te herkennen
3. Voer de URL in waarop je de meldingen wilt ontvangen
4. Kies welke Gebeurtenissen deze webhook moeten activeren
5. Klik op Create

Webhook-secret

Bij het aanmaken van een webhook krijg je een secret key. Daarmee controleer je of binnenkomende verzoeken echt van LabelGrid komen:

• Bewaar de secret veilig
• Controleer de handtekening van binnenkomende verzoeken
• Genereer de secret opnieuw als die is gelekt

---

Beschikbare gebeurtenissen

Stel je webhook in om op deze gebeurtenissen te reageren. De Gebeurtenis-identifier is de waarde die je terugziet in de event-property van de payload en in de X-Webhook-Event-header:

Gebeurtenis-identifier	Beschrijving
delivery.completed	Treedt op wanneer een release succesvol is geleverd aan een outlet
delivery.failed	Treedt op wanneer de levering aan een outlet mislukt
takedown.completed	Treedt op wanneer een takedown-verzoek is voltooid
release.review.status_changed	Treedt op wanneer de reviewstatus van een release verandert
release.preflight.report_ready	Treedt op wanneer het Preflight QC-rapport voor een vastgehouden release klaarstaat om op te halen
stream_radar.flag_created	Treedt op wanneer een Stream Radar-flag wordt geplaatst, of een opgeloste flag heropent bij een nieuwe detectie
stream_radar.flag_resolved	Treedt op wanneer een Stream Radar-flag oplost doordat de detecties zijn gestopt
release.distributed	Treedt op wanneer een release wordt gedistribueerd
payment.statement_ready	Treedt op wanneer een afrekening klaarstaat om te bekijken
transcode.completed	Treedt op wanneer het audio-transcoderen van een track succesvol is afgerond
transcode.failed	Treedt op wanneer het transcoderen van een track mislukt of onvolledig eindigt
distribution.outlet.status_changed	Treedt op bij elke statusovergang van de distributie per outlet

Je kunt meerdere gebeurtenissen selecteren voor één webhook, of aparte webhooks aanmaken voor verschillende gebeurtenistypen.

Je kunt deze lijst ook programmatisch uitlezen: GET /api/public/webhooks/event-types geeft elke gebeurtenis terug samen met een data-schema dat de payloadsleutels en -typen beschrijft, zodat consumers met een strikt schema hun inkomende validatie vooraf kunnen verruimen.

---

Webhooks beheren

Je webhooks bekijken

De webhooklijst toont:

Kolom	Beschrijving
Naam	De naam die je aan de webhook hebt gegeven
URL	Waar de meldingen naartoe gaan
Gebeurtenissen	Aantal ingestelde gebeurtenissen
Status	Actief of inactief
Geslaagd / Mislukt	Aantal geslaagde en mislukte leveringen
Laatst geactiveerd	Wanneer de webhook voor het laatst is aangeroepen

Een webhook bewerken

1. Klik op de actie Edit op de webhookrij
2. Pas de naam, URL of gebeurtenissen aan
3. Klik op Save

Activeren / deactiveren

Wissel de actieve status van een webhook zonder hem te verwijderen:

• Actief - De webhook ontvangt meldingen
• Inactief - De webhook staat op pauze, er worden geen meldingen verstuurd

Een webhook verwijderen

1. Klik op de actie Delete op de webhookrij
2. Bevestig het verwijderen

Gevaar

Verwijderde webhooks kunnen niet worden hersteld.

---

Webhooks testen

Test een webhook voordat je er in productie op vertrouwt:

1. Klik op de actie Test bij je webhook
2. LabelGrid stuurt een testpayload naar je URL
3. Controleer of je endpoint die correct heeft ontvangen en verwerkt

Opmerking

De testpayload komt niet overeen met de vorm van echte gebeurtenissen. Het event-veld in de envelop is "test" en het data-object bevat { "test": true, "message": "...", "timestamp": "..." }. Gebruik hem om de verbinding en de afhandeling van de handtekening te controleren, maar schrijf je gebeurtenis-handlers tegen de echte gebeurtenispayloads die staan beschreven onder Gebeurtenispayloads.

---

Webhook-logs bekijken

Houd webhookactiviteit in de gaten en los problemen op:

1. Klik op de actie View Logs bij een webhook
2. Bekijk de volledige geschiedenis van webhookleveringen

Logdetails

Elke logregel toont:

Veld	Beschrijving
Gebeurtenistype	Welke gebeurtenis deze levering heeft geactiveerd
Responsstatus	HTTP-statuscode van je server
Duur	Hoe lang het verzoek duurde
Poging	Nummer van de herhaalpoging
Tijdstempel	Wanneer de levering plaatsvond

---

Opbouw van de webhookpayload

Wanneer er iets gebeurt, stuurt LabelGrid een POST-verzoek naar je URL met een JSON-payload:

{
  "event": "delivery.completed",
  "timestamp": "2026-05-05T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    // Gebeurtenisspecifieke gegevens
  }
}

Het timestamp-veld gebruikt de ISO 8601-notatie. webhook_id is de ID van je ingestelde webhook (die overeenkomt met de X-Webhook-Id-header).

---

Gebeurtenispayloads

De structuur van het data-object hangt af van het event-type. Alle veldtypen hieronder zijn de JSON-typen zoals ze in de payload zijn geserialiseerd.

delivery.completed

Wordt één keer per outlet afgevuurd wanneer de levering van een release een definitieve succesvolle status bereikt.

{
  "event": "delivery.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete"
  }
}

Veld	Type	Beschrijving
distro_queue_id	integer	Interne queue-ID voor deze leveringspoging
release_id	integer	De geleverde release
label_id	integer	Het label dat eigenaar is van de release, zodat je de gebeurtenis kunt routeren zonder extra lookup
release_cat	string | null	Je catalogusreferentie voor de release
outlet_id	integer | null	De ID van de doel-outlet
outlet_name	string | null	Leesbare naam van de outlet (bijv. "Spotify")
status	string	Altijd "complete" bij deze gebeurtenis

delivery.failed

Wordt één keer per outlet afgevuurd wanneer de levering van een release definitief mislukt. Dezelfde payload als delivery.completed, plus een message-veld.

{
  "event": "delivery.failed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "error",
    "message": "Outlet rejected the delivery: missing ISRC."
  }
}

Veld	Type	Beschrijving
status	string	Een van error, fault, rejected, batch_exception
message	string | null	Reden van het mislukken vanuit de outlet of de distributiepijplijn

Opmerking

Storingen in onze interne infrastructuur (bijvoorbeeld het kopiëren van audiobestanden naar onze leveringsservers mislukt) vuren delivery.failed niet af. Alleen storingen aan DSP-kant en op pijplijnniveau activeren deze gebeurtenis.

takedown.completed

Wordt één keer per outlet afgevuurd wanneer een takedown-verzoek slaagt. Dezelfde vorm als delivery.completed, plus een takedown: true-vlag.

{
  "event": "takedown.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete",
    "takedown": true
  }
}

release.distributed

Wordt één keer per release afgevuurd wanneer de release overgaat naar de leveringsstatus distributed. Vuurt alleen af bij de overgang naar distributed, niet bij latere bewaaracties terwijl de release al gedistribueerd is.

{
  "event": "release.distributed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "delivery_status": "distributed"
  }
}

release.review.status_changed

Wordt afgevuurd telkens als een release tussen reviewstatussen wisselt.

{
  "event": "release.review.status_changed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "previous_status": "to_review",
    "new_status": "approved"
  }
}

Veld	Type	Beschrijving
previous_status	string	Vorige status. Een van draft, to_review, approved, rejected, require_changes, audit
new_status	string	Nieuwe status. Dezelfde set waarden
review_issues	array (optioneel)	Alleen aanwezig bij overgangen naar require_changes en rejected: de problemen die je aandacht vragen. Bij elke andere overgang ontbreekt de sleutel, ga er dus niet van uit dat die er altijd is

Opmerking

De status audit betekent dat een operator de issuecontroles opnieuw heeft uitgevoerd op een release die al was goedgekeurd. Hij wordt nooit door je eigen acties geactiveerd, en een release in audit blijft live op DSP’s terwijl de hercontrole loopt.

release.preflight.report_ready

Treedt op wanneer het kwaliteitsrapport van Preflight QC voor een release in de wachtstand vóór de review klaarstaat om op te halen. Vereist de Preflight QC-uitbreiding op je account.

{
  "event": "release.preflight.report_ready",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "generated_at": "2026-07-07T09:58:12+00:00",
    "profile": { "name": "quality_report", "version": 2 },
    "counts": { "blocking": 1, "informational": 2, "requires_feedback": 1 }
  }
}

Veld	Type	Beschrijving
release_id	integer	De release waartoe het rapport behoort
label_id	integer	Het label dat eigenaar is van de release
release_cat	string | null	Je catalogusreferentie voor de release
release_title	string | null	De titel van de release
generated_at	string	Wanneer de controles klaar waren (ISO 8601). Komt overeen met report.generated_at van het kwaliteitsrapport-endpoint
profile	object	Het kwaliteitsprofiel waarmee de aantallen zijn berekend: {name, version}
counts	object	Alleen totaalaantallen: {blocking, informational, requires_feedback}. Het aantal requires_feedback overlapt de andere twee

Opmerking

De payload bevat nooit de problemen zelf. Haal na ontvangst het volledige rapport op bij het kwaliteitsrapport-endpoint. Zie Preflight QC: de API gebruiken.

stream_radar.flag_created

Wordt afgevuurd wanneer een Stream Radar-flag wordt geplaatst — ofwel een gloednieuwe flag, ofwel een eerder opgeloste flag die heropent bij een nieuwe detectie. Vereist de Stream Radar-uitbreiding op je account. Het transition-veld houdt de twee gevallen uit elkaar: published voor een nieuwe flag, reopened voor een die weer actief is geworden.

{
  "event": "stream_radar.flag_created",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "active",
    "transition": "published",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-07T00:00:00+00:00",
    "estimated_affected_streams": 12500,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": null
  }
}

Veld	Type	Beschrijving
flag_id	integer	De stabiele identifier van de flag; komt overeen met id op de Stream Radar-endpoints
dsp	string	Het platform waarop het patroon is gezien (bijv. spotify)
isrc	string	De ISRC van de betrokken opname
release_id	integer	De release waartoe de opname behoort
track_id	integer | null	De specifieke track, wanneer de ISRC ondubbelzinnig verwijst naar een van je tracks
severity	string	low, medium of high
status	string	active bij deze gebeurtenis
transition	string	published voor een nieuwe flag, reopened wanneer een opgeloste flag weer actief is geworden
first_detected_at	string | null	Wanneer het patroon voor het eerst is gezien voor deze track en dit platform (ISO 8601)
last_detected_at	string | null	De meest recente detectie (ISO 8601)
estimated_affected_streams	integer | null	Een schatting van hoeveel streams erbij betrokken zijn
published_at	string	Wanneer de flag voor het eerst aan je is gemeld (ISO 8601)
resolved_at	string | null	null zolang de flag actief is

stream_radar.flag_resolved

Wordt afgevuurd wanneer een Stream Radar-flag oplost doordat de detecties zijn gestopt. Vereist de Stream Radar-uitbreiding. Dezelfde velden als stream_radar.flag_created (zonder transition), met status op resolved en resolved_at ingevuld.

{
  "event": "stream_radar.flag_resolved",
  "timestamp": "2026-07-14T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "resolved",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-12T00:00:00+00:00",
    "estimated_affected_streams": 18700,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": "2026-07-14T09:55:03+00:00"
  }
}

Opmerking

De webhooklevering van Stream Radar is best-effort. Behandel de Stream Radar-flag-endpoints als de bron van waarheid en gebruik deze events als een seintje om de huidige staat te lezen. Zie Stream Radar: de API gebruiken.

payment.statement_ready

Wordt afgevuurd wanneer een afrekening is gegenereerd en klaarstaat om te bekijken.

{
  "event": "payment.statement_ready",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "payment_request_id": 1024,
    "invoice_number": "INV-2026-001",
    "period": "2026-04-30",
    "amount": 1234.56,
    "total_due_usd": 1234.56,
    "currency": "USD"
  }
}

Veld	Type	Beschrijving
payment_request_id	integer	Interne ID van het betaalverzoek
invoice_number	string	Factuurreferentie van de afrekening
period	string | null	Einddatum van de periode (ISO 8601-datum, YYYY-MM-DD)
amount	number	Bedrag van de afrekening in currency
total_due_usd	number	Totaal van de afrekening omgerekend naar USD
currency	string	ISO 4217-valutacode (standaard USD)

Opmerking

payment.statement_ready is accountgebonden: het bevat noch release_id noch label_id.

transcode.completed en transcode.failed

Treedt op wanneer het audio-transcoderen van een track is afgerond. transcode.completed treedt op bij succes; transcode.failed treedt op wanneer het transcoderen mislukt of onvolledig eindigt. Beide hebben dezelfde payloadvorm.

{
  "event": "transcode.completed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "track_id": 654,
    "transcoder_queue_id": 987,
    "status": "complete",
    "status_message": "transcode_complete",
    "files": [
      { "asset_type_id": 2, "status": "complete" }
    ]
  }
}

Veld	Type	Beschrijving
release_id	integer	De release waartoe de track behoort
label_id	integer	Het label dat eigenaar is van de release
track_id	integer	De track die is getranscodeerd
transcoder_queue_id	integer	Interne transcode-queue-ID
status	string	Ruwe queuestatus: complete, error of incomplete
status_message	string	Veilige, opgesomde redencode: transcode_complete, transcode_error of transcode_incomplete
files	array	Detail per bestand voor de track: {asset_type_id, status} per getranscodeerd bestand

distribution.outlet.status_changed

Treedt op bij elke statusovergang van de distributie per outlet (bijvoorbeeld scheduled → transcoding → batched → complete), niet alleen bij de definitieve die worden gedekt door delivery.completed, delivery.failed en takedown.completed. Deze gebeurtenis is bewust spraakzaam: abonneer je er alleen op als je de volledige voortgang per outlet wilt.

{
  "event": "distribution.outlet.status_changed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "previous_status": "transcoding",
    "status": "batched"
  }
}

Veld	Type	Beschrijving
distro_queue_id	integer	Interne queue-ID voor deze levering
release_id	integer	De release die wordt gedistribueerd
label_id	integer	Het label dat eigenaar is van de release
release_cat	string | null	Je catalogusreferentie voor de release
outlet_id	integer | null	De ID van de doel-outlet
outlet_name	string | null	Leesbare naam van de outlet
previous_status	string | null	De vorige status; null als de rij geen herkende vorige status had
status	string	De nieuwe status

---

Webhook-handtekeningen verifiëren

Elke webhooklevering is ondertekend, zodat je kunt controleren of die echt van LabelGrid komt. Verifieer de handtekening altijd voordat je de gebeurtenis verwerkt.

Request-headers

Elk webhook-POST-verzoek bevat deze headers:

Header	Beschrijving
X-Webhook-Signature	HMAC-SHA256 van de ruwe request-body, kleine letters hex, zonder algoritmeprefix
X-Webhook-Timestamp	Kopie van de timestamp-property uit de body, puur voor het gemak. Valt niet onder de handtekening — gebruik hem nooit om te bepalen of een levering recent is.
X-Webhook-Event	Gebeurtenis-identifier (bijv. delivery.completed)
X-Webhook-Id	De ID van de webhookconfiguratie die de levering ontvangt (geen ID per levering)
User-Agent	LabelGrid-Webhooks/1.0
Content-Type	application/json

Algoritme

• Algoritme: HMAC-SHA256
• Codering: Hexadecimaal in kleine letters
• Prefix: Geen. De waarde is enkel de hex-digest, niet sha256=...
• Ondertekende inhoud: De volledige ruwe JSON request-body — en verder niets. Geen enkele header wordt ondertekend.

De body bevat zelf een timestamp-property, dus die waarde valt wél onder de handtekening. De header X-Webhook-Timestamp is daar alleen een kopie van, meegestuurd voor het gemak, en wie een levering onderschept, kan die header vrij aanpassen zonder de handtekening ongeldig te maken. Wil je weten of een levering recent is, lees timestamp dan uit de geparseerde body, nooit uit de header.

Verificatierecept

1. Lees de ruwe request-body voordat je JSON parseert of transformeert. De geparseerde JSON opnieuw serialiseren kan andere bytes opleveren en de handtekening breken.
2. Bereken HMAC-SHA256(raw_body, your_webhook_secret) en neem de hex-digest in kleine letters.
3. Vergelijk die met X-Webhook-Signature met een vergelijking in constante tijd. Komt hij niet overeen, stop dan hier.
4. Parseer de body pas nu en weiger het verzoek als de timestamp-property daarin ouder is dan je replay-tolerantievenster. We raden 5 minuten aan. Omdat die waarde mee ondertekend is, kan een aanvaller hem niet verversen om een onderschepte levering actueel te laten lijken.

Elke nieuwe poging wordt opnieuw ondertekend met een nieuwe timestamp, dus een venster van 5 minuten weigert nooit een legitieme herhaling, hoe ver in het herhaalschema die ook binnenkomt.

PHP-voorbeeld

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $rawBody, $webhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Parseer pas nadat is bewezen dat de bytes authentiek zijn.
$payload = json_decode($rawBody, true);

// Of een levering recent is, blijkt uit de ONDERTEKENDE timestamp in de body,
// nooit uit de X-Webhook-Timestamp-header.
if (! isset($payload['timestamp'])
    || abs(time() - strtotime($payload['timestamp'])) > 300) {
    http_response_code(401);
    exit('Stale delivery');
}

// ... verwerk de gebeurtenis (zie "Herhaalde leveringen afhandelen" hieronder)
http_response_code(200);

Node.js-voorbeeld

const crypto = require('crypto');

// Express: leg de ruwe body vast VÓÓR elke JSON-middleware
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body; // Buffer
  const signature = req.header('X-Webhook-Signature') || '';

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  const sigBuf = Buffer.from(signature, 'hex');
  const expBuf = Buffer.from(expected, 'hex');

  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return res.status(401).send('Invalid signature');
  }

  // Parseer pas nadat is bewezen dat de bytes authentiek zijn.
  const payload = JSON.parse(rawBody.toString('utf8'));

  // Of een levering recent is, blijkt uit de ONDERTEKENDE timestamp in de body,
  // nooit uit de X-Webhook-Timestamp-header.
  const sentAt = new Date(payload.timestamp).getTime();

  if (Number.isNaN(sentAt) || Math.abs(Date.now() - sentAt) > 5 * 60 * 1000) {
    return res.status(401).send('Stale delivery');
  }

  // ... verwerk de gebeurtenis (zie "Herhaalde leveringen afhandelen" hieronder)
  res.sendStatus(200);
});

Python-voorbeeld

import hmac, hashlib, json
from datetime import datetime, timezone

raw_body = request.get_data()  # Flask: bytes, vóór het parsen van JSON
signature = request.headers.get('X-Webhook-Signature', '')

expected = hmac.new(
    webhook_secret.encode('utf-8'),
    raw_body,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, signature):
    return ('Invalid signature', 401)

payload = json.loads(raw_body)  # pas parsen als de bytes authentiek zijn

delivery_time = datetime.fromisoformat(payload['timestamp'])  # de ONDERTEKENDE waarde, nooit de header
if abs((datetime.now(timezone.utc) - delivery_time).total_seconds()) > 300:
    return ('Stale delivery', 401)

return ('', 200)  # verwerk de gebeurtenis en bevestig daarna

Veelgemaakte fouten

• Aan de hand van de X-Webhook-Timestamp-header bepalen of een levering recent is. Die header is niet ondertekend. Wie een levering onderschept, kan exact dezelfde body en handtekening opnieuw versturen met een verse headerwaarde en komt eindeloos door zo’n controle heen. Lees timestamp in plaats daarvan uit de geparseerde body; die waarde is wél ondertekend.
• De body opnieuw serialiseren voordat je hasht. Frameworks die JSON automatisch parsen (Express express.json(), de standaard request-body van Laravel) verliezen de oorspronkelijke bytes. Leg eerst de ruwe body vast.
• Een vergelijking gebruiken die niet in constante tijd werkt (==, ===). Die is vatbaar voor timingaanvallen. Gebruik altijd hash_equals (PHP), crypto.timingSafeEqual (Node), hmac.compare_digest (Python) of het equivalent in jouw taal.
• Een sha256=-prefix verwachten. De headerwaarde is enkel de hex-digest, zonder prefix.
• De controle op hoe recent een levering is overslaan. Zonder die controle kan een onderschepte levering eindeloos opnieuw naar je endpoint worden gestuurd.
• X-Webhook-Id vertrouwen als leverings-ID. Die identificeert de webhookconfiguratie, niet de afzonderlijke levering, en is evenmin ondertekend.

---

Herhaalde leveringen afhandelen

Webhooklevering werkt at-least-once: een levering die je endpoint al heeft verwerkt, kan alsnog opnieuw binnenkomen als je 2xx-respons verloren ging of pas na de time-out van 10 seconden aankwam, waarna LabelGrid het opnieuw probeert. Een geldige handtekening bewijst dat een verzoek echt is, niet dat je het nog niet hebt afgehandeld.

Leveringen hebben geen unieke ID per levering, dus bouw je eigen idempotentiesleutel op uit de ondertekende payload. Het gebeurtenistype plus de identifiers in data zijn meestal genoeg — bijvoorbeeld delivery.completed plus distro_queue_id, of transcode.completed plus track_id. Leg de sleutel vast zodra je een gebeurtenis verwerkt en negeer alles wat je al hebt vastgelegd.

Gebruik de handtekening of de timestamp niet als sleutel. Elke poging wordt op het moment van verzenden opnieuw ondertekend, dus een herhaling van een gebeurtenis die je al hebt afgehandeld komt binnen met een andere timestamp en een andere handtekening: de sleutel moet uit de identifiers van de gebeurtenis zelf komen.

Combineer dat met de controle hierboven op hoe recent een levering is: die begrenst hoelang een onderschepte levering herbruikbaar blijft, en idempotentie maakt een herhaling onschadelijk, of die nu van een nieuwe poging komt of van een aanvaller binnen dat venster.

---

Limieten en betrouwbaarheid

Verzoeklimieten

Limiet	Waarde
Time-out van het verzoek	10 seconden
Maximale payloadgrootte	64 KB
Maximaal aantal webhooks per gebruiker	10

Reageert je endpoint niet binnen 10 seconden, dan geldt de levering als mislukt en wordt die opnieuw geprobeerd.

Herhaalschema

Geeft je endpoint een status buiten de 2xx-reeks of een time-out, dan probeert LabelGrid het opnieuw met exponentiële backoff:

Poging	Wachttijd voor herhaling
1 → 2	30 seconden
2 → 3	1 minuut
3 → 4	2 minuten
4 → 5	4 minuten
5 → 6	8 minuten
6 → 7	16 minuten
7 → 8	32 minuten
8 → 9	64 minuten
9 → 10	128 minuten

Elk interval bevat 0 tot 30 seconden jitter. Na 10 pogingen (in totaal ongeveer 4,5 uur) wordt de levering gelogd als definitief mislukt en niet meer opnieuw geprobeerd.

Automatische uitschakeling

Als het endpoint van een webhook herhaaldelijk mislukt — opeenvolgende mislukte leveringen zonder één geslaagde levering daartussen — schakelt LabelGrid de webhook automatisch uit, zodat er niet langer wordt geprobeerd een endpoint te bereiken dat duidelijk geen events kan ontvangen. De teller met mislukte leveringen wordt bij elke geslaagde levering op nul gezet, dus een incidentele hapering schakelt een webhook nooit uit; alleen aanhoudend, ononderbroken falen doet dat.

Wanneer een webhook op deze manier wordt uitgeschakeld, ontvangt de eigenaar een e-mail. De e-mail noemt de naam van de webhook en de URL van het endpoint, plus het soort fout dat de uitschakeling veroorzaakte — bijvoorbeeld een verbindingstime-out of herhaalde HTTP-fouten.

Opnieuw inschakelen doe je zelf: herstel je endpoint en zet de webhook weer aan via Profiel → Webhooks. Een uitgeschakelde webhook opnieuw activeren zet de teller met mislukte leveringen op nul. De webhooklijst toont de actieve status en de huidige teller met mislukte leveringen van elke webhook, zodat je een problematisch endpoint in één oogopslag ziet.

Tips voor betrouwbaarheid

• Geef snel (binnen 10 seconden) een 2xx-respons
• Verwerk de gegevens asynchroon nadat je hebt bevestigd
• Verifieer de handtekening van elk verzoek (zie Webhook-handtekeningen verifiëren)
• Maak je handler idempotent — levering werkt at-least-once (zie Herhaalde leveringen afhandelen)
• Houd je aantal mislukte leveringen in de webhooklijst in de gaten
• Bekijk de leveringslogs als je gemiste gebeurtenissen onderzoekt

---

Toepassingen

Geautomatiseerde meldingen

• Stuur Slack-berichten wanneer releases live gaan
• Mail je team wanneer leveringen mislukken
• Werk interne dashboards bij

Workflowautomatisering

• Start marketingcampagnes wanneer releases worden gedistribueerd
• Werk je website bij wanneer er nieuwe content beschikbaar is
• Synchroniseer de status naar externe projectmanagementtools

Monitoring en alerts

• Krijg meteen meldingen bij mislukte leveringen
• Volg de distributievoortgang in realtime
• Houd wijzigingen in de reviewstatus in de gaten

---

Problemen oplossen

Webhook ontvangt geen gebeurtenissen

1. Controleer de status - Staat de webhook op actief?
2. Controleer de URL - Is het endpoint bereikbaar vanaf het internet?
3. Controleer de gebeurtenissen - Zijn de juiste gebeurtenissen geselecteerd?
4. Bekijk de logs - Staan er fouten geregistreerd?

Veel mislukte leveringen

1. Controleer je endpoint - Geeft het 200 OK terug?
2. Controleer de responstijd - Reageert het binnen de time-out?
3. Bekijk de foutmeldingen - Wat gaat er mis?
4. Test handmatig - Stuur een testwebhook

De secret opnieuw genereren

Als je webhook-secret is gelekt:

1. Klik op Regenerate Secret in de webhookinstellingen
2. Werk je applicatie bij met de nieuwe secret
3. De oude secret werkt meteen niet meer

---

Hulp nodig?

Heb je vragen over webhooks, neem dan contact op met ons supportteam.