GETTING STARTED

Inbound webhooks

Inbound webhooks let external systems send JSON payloads into AlgaPSA. Each webhook has a tenant-scoped receiver URL, its own authentication settings, idempotency rules, rate limit, and a handler that either runs a registered direct action or starts a workflow.

Use this page for events sent into AlgaPSA. For events that AlgaPSA sends to your application, see outbound webhooks.

Receiver URL

After you create an inbound webhook, configure the source system to send JSON POST requests to the public receiver URL:

Receiver URL

https://algapsa.com/api/inbound/{tenantSlug}/{webhookSlug}

tenantSlug identifies the tenant route, and webhookSlug is the URL-safe slug on the inbound webhook configuration. The receiver accepts source-specific JSON; the payload shape is defined by the sender and the field mappings you configure.

Management endpoints

Inbound webhook configuration uses the normal API key authentication model. The generated endpoint reference includes the full request and response schemas.

/api/v1/inbound-webhooksGET

List inbound webhook configurations for the tenant.

/api/v1/inbound-webhooksPOST

Create an inbound webhook and receive any one-time generated secret.

/api/v1/inbound-webhooks/actionsGET

List direct-action handlers and their target field schemas.

/api/v1/inbound-webhooks/{id}/testPOST

Dispatch a synthetic request through the saved configuration.

/api/v1/inbound-webhooks/{id}/deliveries/{deliveryId}/replayPOST

Replay a stored delivery against the current handler configuration.

Start with the generated reference for POST /api/v1/inbound-webhooks and the receiver endpoint POST /api/inbound/{tenantSlug}/{webhookSlug}.

Authentication options

Authentication is configured per webhook, so each source system can use the strongest method it supports. Secret values are provided at create or update time and are not returned later.

hmac_sha256auth_type

Verify a configurable signature header. The header may contain sha256=<hex> or a raw hex digest.

bearerauth_type

Require an Authorization bearer token stored as secret material.

ip_allowlistauth_type

Accept requests only from configured exact IPs or CIDR ranges.

path_tokenauth_type

Require a secret token in a configurable query parameter. Use only when the sender cannot sign headers.

Rotate stored secret material with POST /api/v1/inbound-webhooks/{id}/rotate-secret. The replacement is returned once, so store it immediately.

Idempotency

Configure an optional idempotency source to make duplicate deliveries safe. The source can be a request header, such as X-Idempotency-Key, or a JSONata expression evaluated against the request body. AlgaPSA records each delivery and treats repeated keys inside the configured window as duplicate no-ops.

idempotency-source.json

{
  "idempotency_source": {
    "type": "jsonata",
    "value": "event.id"
  },
  "idempotency_window_seconds": 86400
}

Handlers

A verified delivery can run a direct action or start a workflow. Direct actions map JSON fields from the sender payload into a registered AlgaPSA action. Workflow handlers receive a verified envelope with the request body, filtered headers, delivery id, idempotency key, and received timestamp.

direct-action-webhook.json

{
  "name": "RMM device updates",
  "slug": "rmm-device-updates",
  "auth_type": "hmac_sha256",
  "auth_config": {
    "signature_header": "X-RMM-Signature",
    "secret": "replace-with-shared-secret"
  },
  "idempotency_source": {
    "type": "jsonata",
    "value": "event.id"
  },
  "handler_type": "direct_action",
  "handler_config": {
    "action": "upsertAssetByExternalId",
    "field_mapping": {
      "external_id": "device.id",
      "client_external_id": "organization.id",
      "asset_type": "'workstation'",
      "name": "device.hostname",
      "status": "device.status",
      "rmm_snapshot": "$"
    }
  },
  "rate_limit_per_minute": 60,
  "is_active": true
}

Use GET /api/v1/inbound-webhooks/actions to discover the exact action names and target fields available in your tenant before creating direct action mappings.

Testing and sample capture

Use POST /api/v1/inbound-webhooks/{id}/test to send a synthetic payload through the current configuration. To build mappings from a real sender payload, enable sample capture with POST /api/v1/inbound-webhooks/{id}/capture-sample; the next verified request stores its body as the webhook sample until you clear it with the matching DELETE endpoint.

Delivery history and replay

Every inbound request is recorded with authentication status, dispatch status, request metadata, handler outcome, response status, duration, and replay metadata. Inspect deliveries with GET /api/v1/inbound-webhooks/{id}/deliveries and replay a stored delivery with POST /api/v1/inbound-webhooks/{id}/deliveries/{deliveryId}/replay.