Skip to main content

PSA webhooks

Updated

Overview

Outbound webhooks let PSA notify external systems in real time when events happen — a ticket is created, an invoice is paid, an SLA is breached, and so on. Every delivery is signed with an HMAC secret so the receiving system can verify the payload came from PSA. Failed deliveries are retried automatically.

Setting Up an Outbound Webhook

  1. Go to Settings > Webhooks.
  2. Click New Webhook.
  3. Enter the URL of the endpoint that should receive the events (must be HTTPS).
  4. Add a description so you remember what this webhook is for.
  5. Select the events this webhook should receive (see Event Types below).
  6. PSA generates a signing secret automatically. Copy and store it — you will use it to verify incoming requests on your end.
  7. Toggle the webhook Active.
  8. Click Save.

Event Types

Webhooks can subscribe to any combination of the following events:

Event Fires when...
psa.ticket.created A new ticket is created
psa.ticket.updated Any ticket field changes
psa.ticket.resolved A ticket is moved to Resolved
psa.ticket.sla_breached A ticket's SLA resolution time passes
psa.invoice.paid An invoice is fully paid
psa.autopay.failed An autopay charge fails
psa.contract.* Contract created, updated, or expired

Verifying Webhook Signatures

Every POST delivery from PSA includes an X-PSA-Signature header containing an HMAC-SHA256 hash of the raw request body, signed with the webhook's signing secret. On your receiving endpoint, compute the same hash and compare it to the header to confirm the request is genuine.

Webhook Delivery Retries

When a delivery fails (network error, non-2xx HTTP response, timeout), PSA retries automatically with exponential backoff:

Attempt Delay
1 Immediate
2 ~1 minute
3 ~5 minutes
4 ~15 minutes
5 ~30 minutes

After 5 failed attempts, the delivery is marked Dead and no further retries occur. The delivery log retains the request body so you can replay it manually if needed.

Viewing the Delivery Log

  1. Go to Settings > Webhooks.
  2. Open the webhook.
  3. Click Deliveries.

Each delivery shows the event type, HTTP status code, response snippet, attempt number, and timestamps. Use this log to debug failures and confirm successful deliveries.

Testing a Webhook

To verify your endpoint is reachable and correctly processing payloads, you can manually trigger a test delivery:

  1. Open the webhook.
  2. Click Send Test.

PSA sends a sample payload to your endpoint. Check the delivery log and your endpoint's logs to confirm receipt.

Rotating the Signing Secret

If your signing secret is compromised:

  1. Open the webhook.
  2. Click Rotate Secret.
  3. PSA generates a new signing secret. Copy it immediately and update your receiving endpoint.

Frequently Asked Questions

How do I know if my webhook is working?

Check the Deliveries tab. Each attempted delivery is logged with its HTTP status and response snippet. Green means delivered; red means failed. You can also check your own endpoint's access logs.

Can I subscribe the same URL to multiple event types?

Yes. A single webhook can subscribe to as many events as you need. All subscribed events are delivered to the same URL.

What format are webhook payloads in?

All payloads are JSON. The body includes the event type, the event timestamp, and the full object that changed (ticket, invoice, etc.).

Related