Webhooks

Toegang tot en inrichting van eindpunten

Dit zijn uitgaande klantmeldingen, los van inkomende providersynchronisatie en callbacks van de factureringsprovider. Een API-sleutel geeft geen toestemming voor webhookbeheer. Bij opslaan of handmatig verzenden worden de integratierechten gecontroleerd, naast de normale organisatietoegang.

Gebruik een ontvanger die u beheert en die gebeurtenisgegevens mag ontvangen. Plaats geen aanmeldgegevens in de URL en gebruik geen loopback-URL’s of URL’s van privé-infrastructuur. HTTPS is vereist, maar opslaan bevestigt niet wie de eigenaar is, of de ontvanger bereikbaar en het netwerk veilig is, of hoe omleidingen werken.

Ondersteunde gebeurtenisabonnementen

Gebruik precies deze gebeurtenisnamen. Jokertekens worden niet ondersteund. Als u een werkitem na heropening opnieuw voltooit, kan een nieuwe bedrijfsgebeurtenis ontstaan, geen duplicaat van de eerdere gebeurtenis.

Headers van het afleververzoek

Allocyn verstuurt POST met Content-Type: application/json; charset=utf-8. Headernamen zijn niet hoofdlettergevoelig. De handtekening authenticeert het tijdstempel en de berichtinhoud, niet de gebeurtenis- en aflever-ID-headers afzonderlijk; gebruik type uit de geverifieerde berichtinhoud voor betrouwbare verwerking.

Berichtinhoud van automatische gebeurtenissen

Dit fictieve bericht is opgemaakt voor leesbaarheid. id identificeert de bedrijfsgebeurtenis, niet de aflevering; occurredAtUtc is het tijdstip van de gebeurtenis, niet van de nieuwe poging. De envelop bevat geen organisatie-ID, actor of schemaversie. Koppel het eindpunt en geheim in uw ontvangende systeem aan uw organisatie.

Het data-object bevat gebeurtenisspecifieke details, geen volledige momentopname van de entiteit. Wijzigingen kunnen leeg zijn en oldValue/newValue kunnen tekenreeksen of null zijn, ook bij waarden die op getallen lijken. Valideer wat uw proces nodig heeft en accepteer extra velden. Vervolgverzoeken via de openbare API ondersteunen alleen de vier gedocumenteerde collecties.

{
  "id": "11111111-1111-7111-8111-111111111111",
  "type": "WorkItemCompleted",
  "occurredAtUtc": "2026-09-07T10:30:00Z",
  "entityType": "WorkItem",
  "entityId": "22222222-2222-7222-8222-222222222222",
  "data": {
    "changes": {
      "Status": { "oldValue": "InProgress", "newValue": "Done" }
    }
  }
}

Verifieer de handtekening voordat u JSON ontleedt

Bewaar de exact ontvangen bytes van de berichtinhoud voordat u JSON ontleedt. Pas geen leesbare opmaak toe, serialiseer niet opnieuw, normaliseer geen witruimte en wijzig geen escapetekens. Gebruik de letterlijke tekst van de ondertekeningssleutel als UTF-8-sleutel: ook al lijkt deze op Base64, decodeer of trim deze niet en vervang deze niet door een API-sleutel.

Het Node.js-voorbeeld verifieert alleen handtekeningen. Uw ontvanger moet een limiet voor de berichtgrootte afdwingen, dubbele of dubbelzinnige headers weigeren, het geheim veilig ophalen en de ruwe Buffer doorgeven. Het tijdvenster van vijf minuten is aanbevolen ontvangerbeleid, geen garantie van de afzender; controleer het tijdstempel van de poging in plaats van het oudere gebeurtenistijdstip.

Weiger berichten waarvan de verificatie mislukt. Ontleed en valideer na geslaagde verificatie de berichtinhoud en het toegestane gebeurtenistype en sla het bericht duurzaam op of plaats het in een duurzame wachtrij voordat u ontvangst bevestigt. Alleen een geslaagde verificatie voorkomt geen herhaling en valideert geen applicatiegegevens.

message = UTF8(timestampText + ".") followed by the raw payload bytes
key = UTF8(signingSecretText)
digest = HMAC-SHA256(key, message)
signatureHeader = "sha256=" + lowercaseHex(digest)

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAllocynWebhook(options) {
  if (!options || typeof options !== 'object') return false;
  const {
    rawBody, signature, timestamp, secret,
    nowSeconds = Math.floor(Date.now() / 1000),
    toleranceSeconds = 300,
  } = options;

  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret.length) return false;
  if (typeof signature !== 'string' || signature.length !== 71 ||
      !/^sha256=[0-9a-f]{64}$/.test(signature)) return false;
  if (typeof timestamp !== 'string' || !timestamp.length || timestamp.length > 16) return false;

  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) || seconds < 0 || String(seconds) !== timestamp ||
      !Number.isSafeInteger(nowSeconds) || nowSeconds < 0 ||
      !Number.isSafeInteger(toleranceSeconds) || toleranceSeconds < 0 ||
      Math.abs(nowSeconds - seconds) > toleranceSeconds) return false;

  const expected = createHmac('sha256', Buffer.from(secret, 'utf8'))
    .update(Buffer.from(timestamp + '.', 'utf8'))
    .update(rawBody)
    .digest();
  const supplied = Buffer.from(signature.slice('sha256='.length), 'hex');
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

Duplicaten en ontvangstbevestigingen

Retourneer 2xx na duurzame acceptatie, bij voorkeur ruim vóór de time-out van 15 seconden van de afzender, en verwerk langer werk asynchroon. Retourneer een fout als de gebeurtenis niet veilig kon worden geaccepteerd. Retourneer bij een al geaccepteerd duplicaat succes zonder de bijbehorende effecten te herhalen.

Dwing voor automatische gebeurtenissen duurzaam en atomair uniciteit af op uw ingestelde eindpunt plus id uit de geverifieerde berichtinhoud. Vertrouw niet uitsluitend op de niet-ondertekende aflever-ID-header om herhaling te controleren. Handmatige verzendingen hebben mogelijk geen gebeurtenis-ID in de inhoud en hebben een eigen geauthenticeerd schema en idempotentiesleutel nodig. Er is geen garantie op precies één verwerking of een strikte volgorde.

Nieuwe pogingen en herstel

De wachttijden bepalen wanneer een nieuwe poging mogelijk is, geen exacte planning. Fouten bij meerdere afleveringen kunnen een eindpunt uitschakelen voordat één aflevering vijf pogingen bereikt. Nieuwe pogingen behouden de aflever-ID en oorspronkelijke berichtgegevens, maar krijgen een nieuw tijdstempel en een nieuwe handtekening.

Verhelp problemen met de ontvanger, verbinding, het certificaat of geheim, bewerk vervolgens de webhook en schakel Actief opnieuw in om opeenvolgende fouten te resetten. Onvoltooide afleveringen die in aanmerking komen kunnen hervatten; opnieuw inschakelen reset geen afleveringen die al vijf pogingen hebben gehad en er is geen herhaal- of resetbewerking voor zulke uitgeputte afleveringen.

Een eindpunt wijzigen, pauzeren of verwijderen

Bewerk de webhook en selecteer Ondertekeningssleutel vervangen om een nieuw geheim te genereren; kopieer het wanneer het verschijnt. Opslaan zonder vervanging behoudt het geheim. Er is geen respijtperiode voor het oude geheim: latere pogingen, inclusief nieuwe pogingen in de wachtrij, gebruiken de huidige URL en het huidige geheim. Stem wijzigingen af met uw ontvanger; een al lopend verzoek kan nog eerdere waarden gebruiken.

Pauzeren wist de achterstand niet. Verwijderen wist de abonnementen en opgeslagen aflevergeschiedenis van het eindpunt, niet alleen de actieve status. Bewaar benodigde probleemoplossingsinformatie veilig vóór verwijdering of pauzeer om de geschiedenis te behouden. Verwijderen kan ontvangen gebeurtenissen niet intrekken en garandeert niet dat een lopende verzending wordt geannuleerd.

Referentie voor webhookbeheer

Gebruik normale geauthenticeerde organisatietoegang, geen API-sleutel. Plaats /api/organization/integration-operations en het eventuele basispad van de installatie vóór deze routes. GET vereist integrations.view; andere bewerkingen vereisen ook integrations.manage. Gebruik de nieuwste niet-interpreteerbare Base64-versie voor bewerken en verwijderen; laad opnieuw na 409-conflicten. Ongeldige instellingen retourneren 400 en toegangsfouten kunnen 401 of 403 retourneren.

Eindpuntsamenvattingen bevatten id, name, url, enabled, consecutiveFailures, events, deliveries en version. Afleversamenvattingen bevatten id, businessEventId, eventType, attemptCount, statusCode, succeeded, errorSummary en attemptedAtUtc. Ze tonen de laatste poging, geen rij per poging. Lijsten bevatten maximaal 200 recente afleveringen voor de hele organisatie; de interface toont het aantal recente afleveringen.

Handmatige aflevering vereist een actief eindpunt dat op de gebeurtenis is geabonneerd. payloadJson moet een tekenreeks met geldige JSON zijn; deze wordt rechtstreeks verzonden zonder de automatische envelop en heeft geen businessEventId. Dit wijzigt geen bedrijfsrecord. Controleer succeeded in de geretourneerde samenvatting, ook als het beheerverzoek 200 retourneert, en lees vóór gebruik de serialisatiebeperking hieronder.

{
  "name": "Delivery receiver",
  "url": "https://example.com/hooks/allocyn",
  "enabled": false,
  "rotateSecret": false,
  "events": ["WorkItemCompleted", "TimesheetApproved"],
  "version": null
}

Huidige webhookbeperkingen

Geef ondersteuning de eindpuntnaam, het UTC-tijdstip van de poging, de aflever-ID, het gebeurtenistype en de status- of foutsamenvatting. Deel geen ondertekeningssleutels of gevoelige berichtinhoud.

• ProjectUpdated kan worden geselecteerd, maar normale projectwijzigingen genereren andere interne gebeurtenisnamen die niet als webhookabonnement worden ondersteund. Vertrouw er niet op voor meldingen over projectwijzigingen.
• Bij handmatige JSON ondertekent de afzender de aangeleverde tekenreeks en ontleedt en serialiseert deze daarna opnieuw voor verzending. Witruimte, niet-ASCII-tekst en escapetekens kunnen de bytes veranderen. Weiger en meld berichten waarvan de handtekening niet overeenkomt met de ruwe inhoud; normaliseer inkomende JSON niet en schakel verificatie niet uit. Voor betrouwbare verwerking van willekeurige handmatige berichtinhoud is een correctie bij de afzender nodig.
• Automatische publicatie doorzoekt de afgelopen zeven dagen, niet vóór het aanmaken van het eindpunt. Ze leest de vroegste 1.000 gebeurtenissen voordat op ondersteunde abonnementen wordt gefilterd. Dit is geen volledige geschiedenisexport of gegarandeerde verwerking van de achterstand; organisaties met veel gebeurtenissen kunnen gebeurtenissen buiten die batch hebben.
• Elke ronde met nieuwe pogingen bekijkt de 50 oudste onvoltooide mislukte afleveringen voordat wachttijden en ingeschakelde eindpunten worden gecontroleerd. Achterstanden kunnen verwerking vertragen. Uitval, uitgeputte pogingen, volumelimieten of pauzes kunnen hiaten veroorzaken: houd onafhankelijke gegevensafstemming en waarschuwingen aan voor kritiek werk.