nurr.se
Alla guider

Integrationer

Webhooks – skicka händelser till egna system

Var du hittar webhooks

Webhooks finns under Inställningar → Webhooks. Sidan kräver behörighet att hantera företagsinställningar (manage-company-settings).

Skapa en webhook

  1. Klicka Ny webhook.
  2. Fyll i Namn och Endpoint-URL, adressen som ska ta emot händelserna.
  3. Under Händelser väljer du Alla händelser (*) eller enskilda händelser.
  4. Lägg gärna till en Beskrivning och kontrollera att Aktiv är på.
  5. Klicka Spara.

Efter att du sparat visas dialogen Spara din signeringshemlighet nu. Kopiera hemligheten direkt, för den visas inte igen.

Händelser

  • shift.status_changed – ett pass byter status.
  • invoice.generated – en faktura skapas från tidrapporter.
  • timesheet.approved – en tidrapport attesteras.
  • billing_period.closed – en faktureringsperiod stängs.
  • ping – testhändelse.

Varje leverans är en POST med JSON-innehåll som har fälten id, type, created_at, company_id och data. I data finns id, status, datum och belopp, men inga personuppgifter som personnummer.

Krav på adressen

Adressen måste använda HTTPS och får inte innehålla användarnamn eller lösenord. Adresser som pekar mot interna nät, till exempel privata adresser, localhost eller link-local, avvisas. Det kontrolleras både när du sparar och före varje leverans. Omdirigeringar följs inte. Din server ska svara med en 2xx-status inom 15 sekunder.

Verifiera signaturen

Varje leverans har dessa headers:

  • X-Nurrse-Signature – sha256= följt av en HMAC-SHA256 i hex.
  • X-Nurrse-Timestamp – Unix-tid i sekunder.
  • X-Nurrse-Delivery – leverans-id, samma vid omförsök.
  • X-Nurrse-Event – händelsetypen.

Så kontrollerar du signaturen:

  1. Ta den råa request-bodyn exakt som den kom.
  2. Bilda strängen {X-Nurrse-Timestamp}.{body}.
  3. Beräkna HMAC-SHA256 med signeringshemligheten som nyckel och jämför sha256= + hex mot X-Nurrse-Signature med en jämförelse i konstant tid.
  4. Avvisa gamla tidsstämplar och ignorera X-Nurrse-Delivery som du redan har behandlat.

Testa, rotera och följ upp

  • Skicka test skickar en signerad ping till adressen.
  • Rotera hemlighet skapar en ny hemlighet som visas en gång. Den gamla slutar fungera direkt.
  • Senaste leveranser visar de tio senaste leveranserna med Händelse, Status, Svar och Tid. Kortet visar också Senast lyckad och Senast misslyckad.

Omförsök och automatisk inaktivering

En misslyckad leverans görs om upp till tre försök totalt. Väntande försök plockas upp av en kö som körs var femte minut. Om 15 leveranser i rad misslyckas efter alla försök markeras webhooken som Auto-inaktiverad och får inga fler händelser.