Quickstart

Receive your first webhook in three steps.

Before you start

You're an organization administrator in HI Platform.
You have a publicly reachable HTTPS endpoint. For local testing, use a tunnel like ngrok.

1Register your webhook URL

In the customer app, open Integrations → Webhook, paste your HTTPS URL, and save.

Copy the secret immediately. The signing secret is shown once. Store it in your receiver's secret store before closing the dialog. You can rotate it later from the same screen if needed.

2Set up a receiver

A receiver is an HTTPS endpoint that accepts POST and returns 2xx. A minimal Java stub:

@RestController
@RequestMapping("/webhooks")
public class WebhookController {

    @PostMapping
    public ResponseEntity<Void> receive(
            @RequestBody String body,
            @RequestHeader("X-Webhook-Event") String eventType,
            @RequestHeader("X-Webhook-Signature") String signature) {
        // 1. Verify the HMAC signature over the raw body before trusting anything.
        verifySignature(body, signature);

        // 2. Dispatch to your business logic with the event type and the JSON body.
        process(eventType, body);

        // 3. Acknowledge receipt so HI Platform stops retrying.
        return ResponseEntity.ok().build();
    }
}

See Security for a ready-to-paste verifySignature implementation.

3Verify the signature

Every webhook is signed with HMAC-SHA256. Compare the X-Webhook-Signature header against your own HMAC of the raw request body using a constant-time check. Reject requests that don't match with 401 Unauthorized.

A ready-to-paste Java verifier lives on the Security page.

What's next

Events — the full event catalog.
Payloads — JSON schemas for each event.
Security — full signing details and Java verifier.
Delivery — retries, timeouts, idempotency.