Dokumentationsmeny
Docs / Utvecklare / Webhooks

Webhooks

Få signerade JSON-meddelanden när data ändras eller ett jobb blir klart. Händelserna innehåller id och länkar; aktuell data hämtar du med din API-nyckel.

Skapa en prenumeration#

Skapa en prenumeration under Admin → Integrations → Webhooks, eller med en read_write-nyckel genom POST /v1/webhooks:

{
  "name": "Dataset sync",
  "url": "https://hooks.example.com/orbgis",
  "events": ["layer.data_changed", "job.completed", "job.failed"]
}

Lägg till itemId för att följa ett innehållsobjekt. Spara den returnerade secret, som bara visas en gång. Ange fullständiga händelsenamn; jokertecken stöds inte. Högst 20 aktiva webhooks tillåts per organisation.

Händelser#

HändelseNärDatafält
layer.data_changedLagerdata ändras; händelser samlas per lager under ungefär tio sekunder.collectionId, itemId
job.completedEn inläsning eller export lyckas.jobId, kind, status, itemId, collectionId
job.failedEtt jobb misslyckas eller avbryts.Samma jobbfält.
item.createdEtt innehållsobjekt skapas.itemId, type
item.updatedMetadata, ägarskap, mapp eller publicering ändras; händelser samlas under ungefär tio sekunder. Ändringar i själva innehållet utlöser inte händelsen.itemId, type
item.trashedEtt innehållsobjekt flyttas till papperskorgen; skickas innan objektet blir otillgängligt.itemId, type
item.restoredEtt innehållsobjekt återställs.itemId, type
survey.response_submittedEn enkät får ett svar. Läs det på /collections/{collectionId}/items/{objectid}.surveyId, objectid, itemId, collectionId
pingDu begär en testleverans.Tomt objekt.

Åtkomst och leverans#

Händelser levereras bara om prenumerationens ägare får se det berörda innehållet. Ägaren är integrationen vars nyckel skapade prenumerationen, eller personen som skapade den i portalen. Jobbhändelser går bara till den som startade jobbet. Inaktiveras integrationen stoppas leveranserna.

Använd en HTTPS-adress med värdnamn. Privata adresser, IP-adresser och OrbGIS-domäner nekas. Leveransen är ett POST-anrop med tio sekunders tidsgräns och omdirigeringar räknas som fel. Svara snabbt med 2xx och bearbeta händelsen efteråt.

Kontrollera signaturen#

Kroppen innehåller id, type, createdAt, orgId, deliveryId, attempt, data och links. Headers omfattar X-OrbGIS-Event, X-OrbGIS-Delivery och X-OrbGIS-Signature.

  1. Behåll den råa kroppen

    Kontrollera exakt de byte som togs emot innan JSON tolkas. Signaturen ändras om kroppen serialiseras om.

  2. Beräkna och jämför

    Tolka X-OrbGIS-Signature: t=<unix seconds>,v1=<hex>. Beräkna HMAC-SHA256 med din hemlighet över t + "." + raw body och jämför hexvärdet med v1 genom en jämförelse i konstant tid.

  3. Kontrollera tid och dubbletter

    Neka tidsstämplar som avviker mer än fem minuter från din klocka. Undvik dubbel bearbetning genom X-OrbGIS-Delivery, som är samma vid varje nytt leveransförsök.

Hör av dig till OrbGIS för kompletta mottagarexempel i Python och Node.

Nya försök och återställning#

Misslyckade leveranser görs om efter 1 minut, 5 minuter, 30 minuter, 2 timmar, 12 timmar och 24 timmar och får sedan status dead. Leverans sker minst en gång, så dubbletter kan förekomma. Efter 20 fel i följd inaktiveras prenumerationen. Åtgärda mottagaren och aktivera prenumerationen igen för att nollställa räknaren.

EndpointAnvändning
GET /v1/webhooks/{id}/deliveriesSe försök, HTTP-status och tidsåtgång för de senaste 30 dagarna.
POST /v1/webhooks/{id}/pingSkicka en signerad testhändelse.
PATCH /v1/webhooks/{id}Ändra prenumerationen eller ange active för att pausa eller återuppta.
POST /v1/webhooks/{id}/rotate-secretSkapa en ny signeringshemlighet.
DELETE /v1/webhooks/{id}Radera prenumerationen.