Verify, test, and retry webhooks

Webhooks10 minIntermediate

Once a webhook is configured, the day-to-day operational loop is: send a test delivery, verify a signature, inspect the delivery history, and retry anything that failed. The webhook API exposes a dedicated endpoint for each step.

Endpoints used in this guide

POST/api/v1/webhooks/{id}/testSend a signed test delivery using the stored secret.

POST/api/v1/webhooks/testSend an ad-hoc test to an override URL.

POST/api/v1/webhooks/verifyVerify an X-Alga-Signature value server-side.

GET/api/v1/webhooks/{id}/deliveriesList delivery attempts.

GET/api/v1/webhooks/{id}/deliveries/{delivery_id}Inspect one delivery in detail.

POST/api/v1/webhooks/{id}/deliveries/{delivery_id}/retryRetry a failed delivery.

Send a signed test delivery

The per-webhook test endpoint sends a signed envelope to the webhook's configured URL using the live signing secret. The attempt is recorded in the delivery history with is_test=true and skips the per-webhook rate limit so you can re-run it as often as you like during onboarding.

curl

curl -X POST "https://algapsa.com/api/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ALGA_API_KEY" \
  -d '{
    "test_event_type": "ticket.created"
  }'

For ad-hoc testing without persisting a webhook, use POST /api/v1/webhooks/test with override_url:

curl

curl -X POST "https://algapsa.com/api/v1/webhooks/test" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ALGA_API_KEY" \
  -d '{
    "test_event_type": "ticket.assigned",
    "override_url": "https://webhook.site/your-id-here"
  }'

Verify a signature

Pass the canonical X-Alga-Signature header value and the raw request body. Either webhook_id or secret_vault_path tells AlgaPSA which secret to verify against. Only sha256 is honored.

curl

curl -X POST "https://algapsa.com/api/v1/webhooks/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ALGA_API_KEY" \
  -d '{
    "algorithm": "sha256",
    "webhook_id": "'$WEBHOOK_ID'",
    "signature": "t=1715095451,v1=8d6c...hex...",
    "body": "{\"event_id\":\"9f3b...\",\"event_type\":\"ticket.assigned\",...}"
  }'

Most integrators verify signatures locally instead of calling this endpoint — see the Webhooks reference for ready-to-paste verification code in TypeScript, Python, Go, and PHP.

Inspect the delivery history

The per-webhook delivery list returns paginated attempts — both real events and is_test=true records. Filter by status (pending, delivered, failed, retrying, abandoned) when triaging a problem.

curl

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

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

Retry a failed delivery

Retry re-sends the exact same payload to the same URL and writes a new attempt row on the same delivery record. Use it after fixing your receiver to clear out the queue without having to re-trigger source events.

curl

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

What to look for in delivery records

status — the terminal value tells you whether AlgaPSA gave up (abandoned) or is still retrying.
response_status_code + response_body — the receiver's reply, truncated. 4xx responses usually mean a schema or auth problem on your side; 5xx and timeouts will be retried automatically.
duration_ms — if it's near 10000, your receiver hit the 10-second delivery timeout.
attempt_number + the auto-disable rule (24 hours of failed-only deliveries disables the webhook) — recurring failures will trip the guard.