Webhooks

Strise kan skicka händelser till en HTTPS-slutpunkt som du kontrollerar. När något viktigt händer i din portfölj – en Granska slutförs, ett kundinriktat formulär ändrar status – skickar Strise en signerad HTTP-förfrågan till din server i nära realtid, så att dina system kan reagera utan polling.

Var du konfigurerar

Hantera prenumerationer under Inställningar → Team → Webhooks. Endast teamansvariga kan skapa eller redigera dem. Varje prenumeration har en slutpunkts-URL, den uppsättning händelsetyper du vill ha och ett reglage för aktiv status.

Händelser som stöds

Fler händelser kommer att läggas till över tid. Kontakta Strise om det är någon du skulle vilja se.

newStatus för form.status.changed kan också vara INCONCLUSIVE – formuläret slutfördes, men dokumentverifieringssteget kunde inte fastställas slutgiltigt.

Skicka en testhändelse

När en prenumeration är aktiv kan du utlösa en verklig leverans vid behov för att kontrollera din slutpunkt – du behöver inte vänta på att en skarp Granska ska bli klar eller att ett formulär ska ändra status. Under Inställningar → Team → Webhooks, använd prenumerationens åtgärd Skicka mock-händelse, välj en av händelsetyperna som den prenumererar på, granska JSON-payloaden och skicka.

Strise publicerar testhändelsen genom samma pipeline som en produktionsleverans: samma signerade kuvert och OIDC-token, skickat till slutpunkten du registrerade. En testhändelse testar därför din signaturverifiering och din hanterare från början till slut, mot en payload som du kan se i förväg. Skickande är begränsat till teamansvariga, och endast medan prenumerationen är aktiv.

Samma händelse-id vid varje omsändning

Att skicka om samma mock-händelse genererar en leverans med samma id varje gång. Detta är avsiktligt: det låter dig bekräfta att din deduplicering fungerar. En mottagare som deduplicerar på händelsens id bearbetar den första leveransen och ignorerar identiska omsändningar – så om en upprepad testhändelse slutar dyka upp nedströms gör din deduplicering sitt jobb.

Vad du tar emot

En HTTPS POST till slutpunkten du registrerade, med:

• Headern Authorization: Bearer <JWT> – tokenen du verifierar (nedan).
• Händelsen som rå JSON-body. Kuvertet innehåller allt du behöver för att identifiera, dirigera och deduplicera en leverans – inga andra headers krävs för bearbetning.

{
  "id": "4bdf74b2-0d8e-3379-9739-cba7db9b602d",
  "version": "1",
  "eventType": "form.status.changed",
  "teamId": "b07e18b1-45bf-4d5d-877e-ad0374d70111",
  "subscriptionId": "76a48168-145b-495a-8cec-0ee929d8c15c",
  "timestamp": "2026-05-27T12:41:58.985818515",
  "data": {
    "formInstanceId": "…",
    "entityId": "…",
    "entityKind": "Company",
    "oldStatus": "IN_PROGRESS",
    "newStatus": "SUCCESS"
  }
}

Din slutpunkt måste vara HTTPS – Strise skickar inte till vanlig HTTP, och payloadens integritet under överföring förlitar sig på TLS. Se Bekräfta leveransen nedan för hur du svarar.

Verifiera signaturen

Varje leverans bär en Authorization: Bearer <JWT>-header som innehåller en Google-utfärdad OIDC-token, signerad på uppdrag av Strises leveranstjänstkonto. Att verifiera den bevisar att förfrågan kom från Strise och nådde dig oförändrad. Verifiera den innan du litar på payloaden.

Vad du ska verifiera mot

email är ett fast Strise-värde (ovan). aud är den slutpunkts-URL du angav när du skapade prenumerationen – Strise sätter tokenens audience till din push-slutpunkt.

⚠️ Den viktigaste regeln

En giltig Google-signatur ensam bevisar inte att förfrågan kommer från Strise. Vem som helst med ett Google Cloud-konto kan få en Google-signerad OIDC-token (iss: https://accounts.google.com, giltig signatur). Det som knyter en token till Strise är email-anspråket (leveranstjänstkontot) tillsammans med aud-anspråket (din slutpunkt).

Kontrollera alltid både email och aud efter att ha verifierat signaturen. Att endast verifiera signaturen eller endast utfärdaren lämnar dig sårbar för spoofing.

Verifieringssteg

1. Extrahera tokenen från headern Authorization: Bearer.
2. Hämta Googles publika nycklar (biblioteken nedan cachar och roterar dem åt dig).
3. Verifiera signaturen och standardanspråken (iss, exp).
4. Kontrollera att aud motsvarar din registrerade slutpunkts-URL.
5. Kontrollera att email är lika med webhook-delivery@strise-prod.iam.gserviceaccount.com (och att email_verified är true).
6. Först därefter kan du lita på och bearbeta händelsens JSON i förfrågans body.

Kodexempel

Varje exempel verifierar headern och returnerar claims vid framgång. Ersätt EXPECTED_AUDIENCE med slutpunkts-URL:en du registrerade.

Node.js — google-auth-library

import { OAuth2Client } from 'google-auth-library'

const client = new OAuth2Client()
const EXPECTED_EMAIL = 'webhook-delivery@strise-prod.iam.gserviceaccount.com'
const EXPECTED_AUDIENCE = 'https://your-domain.example.com/strise-webhook'

// Throws if the token is missing, invalid, expired, or not issued by Strise.
export async function verifyStriseWebhook(authorizationHeader) {
  if (!authorizationHeader?.startsWith('Bearer ')) throw new Error('missing bearer token')
  const token = authorizationHeader.slice('Bearer '.length)

  // Verifies the Google signature (JWKS), iss, exp, and aud.
  const ticket = await client.verifyIdToken({ idToken: token, audience: EXPECTED_AUDIENCE })
  const claims = ticket.getPayload()
  if (claims.email !== EXPECTED_EMAIL || claims.email_verified !== true) {
    throw new Error('token not issued by Strise')
  }
  return claims
}

Python — google-auth

from google.oauth2 import id_token
from google.auth.transport import requests as google_requests

EXPECTED_EMAIL = "webhook-delivery@strise-prod.iam.gserviceaccount.com"
EXPECTED_AUDIENCE = "https://your-domain.example.com/strise-webhook"

def verify_strise_webhook(authorization_header: str) -> dict:
    if not authorization_header.startswith("Bearer "):
        raise ValueError("missing bearer token")
    token = authorization_header[len("Bearer "):]

    # Verifies the Google signature (JWKS), iss, exp, and aud.
    claims = id_token.verify_oauth2_token(token, google_requests.Request(), audience=EXPECTED_AUDIENCE)
    if claims.get("email") != EXPECTED_EMAIL or not claims.get("email_verified"):
        raise ValueError("token not issued by Strise")
    return claims

Go — google.golang.org/api/idtoken

import (
	"context"
	"fmt"
	"strings"

	"google.golang.org/api/idtoken"
)

const (
	expectedEmail    = "webhook-delivery@strise-prod.iam.gserviceaccount.com"
	expectedAudience = "https://your-domain.example.com/strise-webhook"
)

// VerifyStriseWebhook returns the verified claims, or an error if the token is
// missing, invalid, expired, or not issued by Strise.
func VerifyStriseWebhook(ctx context.Context, authorizationHeader string) (*idtoken.Payload, error) {
	token := strings.TrimPrefix(authorizationHeader, "Bearer ")
	if token == authorizationHeader {
		return nil, fmt.Errorf("missing bearer token")
	}

	// Validate verifies the Google signature (JWKS), iss, exp, and aud.
	payload, err := idtoken.Validate(ctx, token, expectedAudience)
	if err != nil {
		return nil, err
	}
	if payload.Claims["email"] != expectedEmail || payload.Claims["email_verified"] != true {
		return nil, fmt.Errorf("token not issued by Strise")
	}
	return payload, nil
}

Bekräfta leveransen

Svara med valfri 2xx-statuskod för att bekräfta mottagandet. Ett svar som inte är 2xx (eller en timeout) gör att Strise försöker skicka samma payload igen.

Bekräfta alltid, även om din egen bearbetning misslyckas. Om din nedströmshanterare genererar fel – en databasskrivning misslyckas, din kö är full, ett undantag kastas – svara ändå med 2xx och hantera felet på din sida (logga, larma, försök igen från din egen kö). Ett svar som inte är 2xx talar om för Strise att meddelandet inte nådde dig, så vi fortsätter att försöka leverera den identiska payloaden igen. Det åtgärdar sällan ett nedströmsfel och förstärker bara bruset på din sida.

Vanliga felkällor

• Verifiera signaturen men inte email/aud – signaturen bevisar bara att Google utfärdade tokenen, inte att Strise gjorde det. Kontrollera alltid båda anspråken. Detta är det vanligaste misstaget.
• Avkoda utan att verifiera – att base64-avkoda JWT-bodyn för att läsa anspråk utan att validera signaturen innebär att du litar på data från en angripare. Använd ett bibliotek som verifierar.
• Felaktig aud – audience måste motsvara den exakta slutpunkts-URL:en du registrerade (den URL som Strise skickar till), inte ett tjänstenamn eller en annan sökväg.
• Klockavvikelse – exp ligger ungefär en timme framåt i tiden. Om din servers klocka drar sig avvisas giltiga tokens. Håll den NTP-synkroniserad; biblioteken ovan tolererar några sekunders avvikelse.
• Borttagen Authorization-header – vissa lastbalanserare och API-gateways tar bort eller skriver om Authorization. Se till att den når din applikation intakt.
• Nyckelrotation – Google roterar sina signeringsnycklar regelbundet. Alla tre bibliotek hämtar och cachar JWKS och hanterar rotationen automatiskt; hårdkoda (pinna) aldrig en nyckel.
• Återuppspelning (replays) – en fångad token är giltig fram till exp (~1 timme). Deduplicera på händelsens id i payloaden (stabilt över återleveranser) så att ombearbetning är ofarlig.