Webhooks - TIC Identity

Översikt

Webhooks skickas som HTTP POST-anrop till din angivna URL när specifika händelser inträffar. Alla webhooks signeras med HMAC-SHA256 för att säkerställa autenticitet.

Händelsetyper

Händelse	Beskrivning
`auth.completed`	Autentisering slutförd
`sign.completed`	Signering slutförd
`enrichment.completed`	Berikning slutförd
`enrichment.failed`	Berikning misslyckades

Signaturverifiering

Varje webhook innehåller en X-Ormeo-Signature-header med en HMAC-SHA256-signatur. Verifiera alltid signaturen innan du processar webhooket.

Headers

Header	Beskrivning
`X-Ormeo-Signature`	HMAC-SHA256-signatur av request body
`X-Ormeo-Timestamp`	Unix-timestamp när webhooket skickades
`X-Ormeo-Event`	Händelsetyp (t.ex. `enrichment.completed`)
`Content-Type`	`application/json`

Verifieringsexempel

using System.Security.Cryptography;
using System.Text;

public bool VerifySignature(string payload, string signature, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var computed = Convert.ToHexString(hash).ToLowerInvariant();
    return computed == signature;
}

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return computed === signature;
}

Viktigt

Avvisa alltid webhooks med ogiltig signatur. Din webhook-hemlighet hittar du i tenant-inställningarna.

Berikning-webhooks

enrichment.completed

Skickas när berikning har slutförts. Innehåller en tidsbegränsad URL för att hämta berikningsdata.

Payload

{
  "event": "enrichment.completed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "enrichmentId": "f1e2d3c4-b5a6-7890-cdef-123456789abc",
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "secureUrl": "/api/v1/enrichment/data/f1e2d3c4-b5a6-7890-cdef-123456789abc",
    "expiresAtUtc": "2024-01-15T14:45:00Z",
    "state": "din-state-parameter"
  }
}

Fält	Beskrivning
`enrichmentId`	Unikt ID för berikningsförfrågan
`sessionId`	ID för den autentiserade sessionen
`status`	`completed`
`secureUrl`	URL för att hämta berikningsdata (giltig 30 min)
`expiresAtUtc`	Tidpunkt när URL:en slutar gälla
`state`	Ditt state-värde om du skickade med ett

Ingen känslig data i webhooket

Webhooket innehåller aldrig berikningsdata direkt. Du måste hämta data separat via secureUrl med din API-nyckel.

enrichment.failed

Skickas när berikning har misslyckats.

Payload

{
  "event": "enrichment.failed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "enrichmentId": "f1e2d3c4-b5a6-7890-cdef-123456789abc",
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "failed",
    "error": "No data available for requested sources",
    "state": "din-state-parameter"
  }
}

Autentisering- och signeringswebhooks

auth.completed

Skickas när en autentisering har slutförts.

Payload

{
  "event": "auth.completed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "complete",
    "provider": "bankid",
    "user": {
      "personalNumber": "199001011234",
      "givenName": "Anna",
      "surname": "Andersson",
      "name": "Anna Andersson"
    },
    "state": "din-state-parameter"
  }
}

sign.completed

Skickas när en signering har slutförts. Innehåller även signaturdata.

Payload

{
  "event": "sign.completed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "complete",
    "provider": "bankid",
    "user": {
      "personalNumber": "199001011234",
      "givenName": "Anna",
      "surname": "Andersson",
      "name": "Anna Andersson"
    },
    "signature": {
      "value": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
      "ocspResponse": "MIIHfgoBAKCCB3cwggdzBg..."
    },
    "state": "din-state-parameter"
  }
}

Återförsök

Om din endpoint inte svarar med HTTP 2xx försöker vi igen med exponentiell backoff:

Försök 1: Omedelbart
Försök 2: Efter 30 sekunder
Försök 3: Efter 2 minuter
Försök 4: Efter 10 minuter
Försök 5: Efter 30 minuter

Efter 5 misslyckade försök markeras webhooket som misslyckat och inga fler försök görs.

Best practices

Svara snabbt: Returnera HTTP 200 så snart som möjligt. Gör tung bearbetning asynkront.
Verifiera signaturen: Kontrollera alltid X-Ormeo-Signature innan du processar webhooket.
Hantera dubbletter: Samma webhook kan levereras flera gånger. Använd enrichmentId eller sessionId för idempotens.
Använd HTTPS: Webhook-URL:er måste använda HTTPS i produktion.
Kontrollera timestamp: Avvisa webhooks äldre än 5 minuter för att förhindra replay-attacker.

Testa webhooks

I testmiljön kan du använda verktyg som webhook.site för att inspektera inkommande webhooks.

# Begär berikning med webhook-URL
curl -X POST https://id.tic.io/api/v1/enrichment \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "types": ["SPAR", "CompanyRoles"],
    "webhookUrl": "https://webhook.site/your-unique-url",
    "state": "test-123"
  }'