Skip to main content

Webhook

Slug: webhook
Provider: HMAC-signed JSON HTTP POST to any endpoint
Inbound ACK: Yes — your endpoint POSTs back an ACK event

How it works​

PSAPLink sends a signed JSON payload to a configured HTTP(S) endpoint when a notification is dispatched. The request is signed with an HMAC-SHA256 signature using the configured secret, allowing your endpoint to verify authenticity. Your endpoint can then POST back an acknowledgement to POST /api/v1/inbound/webhook.

Configuration schema​

FieldTypeRequiredDescription
urlstringYesHTTP or HTTPS endpoint URL to receive notifications.
secretstringYesHMAC-SHA256 signing secret. Your endpoint verifies this signature.
methodstringNoHTTP method (default: POST).
headersobjectNoAdditional HTTP headers to include in every request (e.g. API keys).
timeout_secondsintegerNoRequest timeout in seconds (default: 10).

Create a channel​

POST /api/v1/transport-channels
Authorization: Bearer <token>
Content-Type: application/json

{
  "transport_type_slug": "webhook",
  "name": "Operations Webhook",
  "config": {
    "url": "https://your-system.example.com/psaplink/notify",
    "secret": "your-hmac-secret",
    "headers": {
      "X-Api-Key": "your-api-key"
    }
  }
}

Outbound payload format​

PSAPLink sends a JSON body with incident and delivery metadata. The request includes:

X-PSAPLink-Signature: sha256=<HMAC-SHA256 of request body>
Content-Type: application/json

Verify the signature on your endpoint:

import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert "sha256=" + expected == request.headers["X-PSAPLink-Signature"]

Inbound ACK callback​

To acknowledge a notification, POST back to PSAPLink:

POST /api/v1/inbound/webhook
Content-Type: application/json

{
  "event": "ack",
  "delivery_id": "<delivery_id_from_notification_payload>"
}

PSAPLink validates the WEBHOOK_SECRET env var against the request signature before processing.

Test the channel​

POST /api/v1/transport-channels/{id}/test
Authorization: Bearer <token>

Limitations​

  • Your endpoint must respond with HTTP 2xx within the configured timeout_seconds; non-2xx responses are recorded as delivery failures.
  • The global WEBHOOK_SECRET env var is used to validate inbound ACK callbacks — it is separate from the per-channel secret used for outbound signatures.