Question 1

What are webhooks?

Accepted Answer

Webhooks send real-time HTTP POST notifications to your server when events happen during AI conversations. Instead of checking for updates, your system gets notified instantly when:

A support ticket is created
An appointment is booked, cancelled, or rescheduled
A phone call or chat session ends
A call recording becomes available
A maintenance request is submitted
An emergency is escalated

Staffify supports 17 event types across 4 categories: Universal, Customer Service, Appointments, and Property Management.

Question 2

How do I set up webhooks?

Accepted Answer

Go to Tools, then Webhooks in your dashboard. Click Create Endpoint, enter your server's HTTPS URL and give it a name, select the events you want to receive, and click Create. After creation, your webhook secret is displayed once - copy it immediately and store it securely (e.g., in an environment variable). Use the Test button to send a test.ping event and verify your endpoint is reachable before going live.

Question 3

What webhook events are available?

Accepted Answer

Universal Events: call.completed (phone call ended), chat.completed (widget chat session ended), call.transferred (call transferred to human), contact.collected (customer contact info collected), call.recording_available (recording ready for download), call.analyzed (AI analysis completed). Customer Service: ticket.created, ticket.note_added, ticket.resolved, ticket.status_changed. Appointments: appointment.booked, appointment.cancelled, appointment.rescheduled. Property Management: maintenance_request.created, maintenance_request.updated, emergency.escalated, tenant.identified.

Question 4

How do I verify webhook signatures?

Accepted Answer

Every webhook delivery includes an X-Webhook-Signature header with an HMAC-SHA256 signature. To verify: get the X-Webhook-Signature and X-Webhook-Timestamp headers, check the timestamp is within 5 minutes (replay protection), compute HMAC-SHA256(secret, timestamp + "." + raw_body), and compare your computed signature with the header value using constant-time comparison. The signature format is sha256=<hex>. See the technical docs at docs.staffifyai.com/webhooks for complete code examples.

Question 5

What headers are included in webhook deliveries?

Accepted Answer

Every webhook POST request includes: X-Webhook-Signature (HMAC-SHA256 signature for verification), X-Webhook-Timestamp (Unix timestamp when sent), X-Webhook-Event (event type, e.g., ticket.created), X-Webhook-Delivery (unique delivery ID for deduplication), User-Agent (Staffify-Webhooks/1.0), and Content-Type (application/json).

Question 6

What is the webhook retry policy?

Accepted Answer

Staffify expects a 2xx response within 10 seconds. If delivery fails, retries occur with increasing delays: 1st attempt immediately, 2nd attempt after 30 seconds, 3rd attempt after 2 minutes, and 4th (final) attempt after 15 minutes. After 50 consecutive failures across all deliveries, the endpoint is automatically disabled. You can re-enable it from the dashboard at any time, which resets the failure counter.

Question 7

Can I assign webhooks to specific agents?

Accepted Answer

Yes. When creating or editing an AI agent, you will see a Webhook Endpoints section in the Integrations step. Toggle endpoints on or off for each agent. This lets you route events from different agents to different backend systems, reduce noise by only receiving events for specific agents, and test webhooks on a single agent before rolling out company-wide. If no agents are assigned to an endpoint, it receives events from all agents in your company.

Question 8

Are sensitive verification answers included in webhooks?

Accepted Answer

No. Customer verification answers (date of birth, SSN, account numbers, etc.) are automatically redacted from webhook payloads. For example, a transcript might show "ASSISTANT: Could you confirm your date of birth? USER: [DATE OF BIRTH REDACTED]". Only the customer's sensitive answers are redacted while the AI's questions remain visible for context. This applies to all transcript types: phone calls, voice widgets, and text widgets.

Question 9

How long are webhook delivery logs kept?

Accepted Answer

Delivery logs are retained for 7 days. To view them, go to Tools, then Webhooks, click on any endpoint, and click Delivery Logs. You can filter logs by event type and delivery status (delivered, failed, retrying). Each log entry shows the request payload, response status, response body, and delivery time.

Question 10

What does the webhook payload look like?

Accepted Answer

Every webhook sends a JSON payload with an envelope format containing: id (unique delivery ID with wh_ prefix and UUID), event (event type that triggered the webhook), timestamp (ISO 8601 timestamp of when the event occurred), and data (event-specific payload that varies by event type). See the technical docs at docs.staffifyai.com/webhooks for detailed payload examples for each event type.

Question 11

Why is my webhook endpoint disabled?

Accepted Answer

Endpoints are automatically disabled after 50 consecutive delivery failures. Common causes include your server being down or unreachable, your endpoint returning non-2xx status codes, your endpoint taking longer than 10 seconds to respond, or DNS resolution failing for your URL. To fix: check your server logs and fix the underlying issue, go to Tools then Webhooks, click the disabled endpoint and click Re-enable, then use the Test button to verify it works. Re-enabling resets the failure counter.

Question 12

Can I regenerate my webhook secret?

Accepted Answer

Yes. Go to Tools, then Webhooks, click on the endpoint, and click Regenerate Secret. Important: the old secret is immediately invalidated, the new secret is displayed once so copy it right away, update your server's verification code with the new secret before the next delivery, and any in-flight deliveries signed with the old secret will fail verification on your end.