Create and manage webhooks

Webhooks12 minIntermediate

The webhook API lets you create outgoing webhook configurations, subscribe them to event types, and inspect delivery health from inside AlgaPSA. AlgaPSA generates the HMAC signing secret for you and returns it once at creation time.

Endpoints used in this guide

GET/api/v1/webhooksList webhook configurations.

POST/api/v1/webhooksCreate a webhook configuration.

GET/api/v1/webhooks/eventsList available webhook event types.

GET/api/v1/webhooks/{id}Fetch one webhook configuration.

GET/api/v1/webhooks/{id}/healthRead webhook health (success rate, last delivery).

GET/api/v1/webhooks/{id}/analyticsRead per-webhook delivery analytics.

POST/api/v1/webhooks/{id}/secret/rotateRotate the signing secret.

Minimal create payload

The required fields are name, url, and at least one entry in event_types. AlgaPSA generates a 32-byte signing secret automatically — you do not supply one.

curl

curl -X POST "https://algapsa.com/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ALGA_API_KEY" \
  -d '{
    "name": "Ticket notifications",
    "url": "https://example.com/webhooks/alga",
    "event_types": ["ticket.created", "ticket.assigned", "ticket.status_changed"],
    "is_active": true,
    "verify_ssl": true
  }'

The signing secret is returned once

The create response includes a one-time signing_secret value. Copy it into your secret manager immediately — AlgaPSA stores only a vault reference internally and there is no reveal endpoint. If you lose it, rotate it (see below).

response

{
  "data": {
    "webhook_id": "f4a1...",
    "name": "Ticket notifications",
    "url": "https://example.com/webhooks/alga",
    "event_types": ["ticket.created", "ticket.assigned", "ticket.status_changed"],
    "is_active": true,
    "signing_secret": "kQqB...base64url...",
    "created_at": "2026-05-07T15:24:11.482Z"
  }
}

Pick event types intentionally

Ticket events (ticket.created, ticket.updated, ticket.status_changed, ticket.assigned, ticket.closed, ticket.comment.added) are wired to the live delivery pipeline today. Other events listed by GET /webhooks/events are reserved — subscribing now is safe but you will not receive deliveries for them yet.

curl

curl -X GET "https://algapsa.com/api/v1/webhooks/events" \
  -H "X-API-Key: $ALGA_API_KEY"

Inspect health and analytics

/health returns a single status (healthy, failing, or disabled) plus the success rate and last-delivery timestamps. /analytics returns delivery counts broken out by status, event type, and time bucket.

curl

curl -X GET "https://algapsa.com/api/v1/webhooks?page=1&limit=25" \
  -H "X-API-Key: $ALGA_API_KEY"

curl -X GET "https://algapsa.com/api/v1/webhooks/$WEBHOOK_ID/health" \
  -H "X-API-Key: $ALGA_API_KEY"

curl -X GET "https://algapsa.com/api/v1/webhooks/$WEBHOOK_ID/analytics" \
  -H "X-API-Key: $ALGA_API_KEY"

Rotate the signing secret

Rotation invalidates the old secret immediately and returns a new plaintext value once. Update your verification code and any secret-manager entries before deploying. Your endpoint will start receiving signatures computed with the new secret as soon as the call returns.

curl

curl -X POST "https://algapsa.com/api/v1/webhooks/$WEBHOOK_ID/secret/rotate" \
  -H "X-API-Key: $ALGA_API_KEY"

Design notes

Use a dedicated endpoint in your own system for each webhook stream. It makes signature verification, idempotency, and retries simpler than multiplexing unrelated events together.
Treat X-Alga-Event-Id as the idempotency key: deliveries can repeat. See Webhooks reference for the envelope and verification recipe.
AlgaPSA auto-disables a webhook after 24 hours of failed-only deliveries. Re-enable it with PUT /api/v1/webhooks/{id} after fixing the receiver.