How to Set Up Webhooks (Receive Call Data)

Webhooks allow you to receive real-time notifications and full call data directly in your own systems as soon as a call is completed or fails. Instead of manually checking the SkipCalls dashboard, your server or third-party tools (like Zapier, HubSpot, or Salesforce) can be automatically updated with transcripts, summaries, and extracted data.

Use Cases

Sync call results to your database: Automatically save every call record and transcript into your internal systems.
Trigger workflows: Start automated follow-ups or internal processes immediately after a call ends.
Update CRM records: Keep your customer data up-to-date with the latest conversation details without manual entry.
Send notifications: Get alerted in Slack, Discord, or via email whenever a high-priority call is completed.

Before You Start

An active SkipCalls account.
A destination URL (endpoint) to receive the data. You can use your own server endpoint or a tool like webhook.site for testing.
(Optional) A secret key if you want to verify the authenticity of the incoming data.

Webhook Events

Event	Description
`CALL_COMPLETED`	An outgoing call finished successfully.
`CALL_FAILED`	An outgoing call failed (e.g., busy, no answer, or technical error).
`INCOMING_CALL_COMPLETED`	An incoming call to one of your numbers finished successfully.
`INCOMING_CALL_FAILED`	An incoming call failed to connect or process.

Step-by-Step Setup

Navigate to Settings → API Keys in your SkipCalls dashboard.
Click on the Webhooks tab.
Click the "Create Webhook" button.
Name: Give your webhook a descriptive name (e.g., "CRM Integration").
URL: Enter the destination URL where SkipCalls should send the data.
Events: Select the events you want to subscribe to (e.g., CALL_COMPLETED).
Secret (Optional): Enter a secret string if you plan to verify the X-Webhook-Signature header for security.
Format: Choose Default for full nested data or Zapier for a flattened structure optimized for automation tools.
Click Save.
Test your setup by clicking the "Test Webhook" button next to your new webhook.

What’s in the Payload?

Each webhook contains a rich set of data about the call:

Call Info: Unique ID, title, status, duration, and timestamps (started, finished).
Agent Info: The name and ID of the AI agent that handled the call.
Phone Numbers: The "from" and "to" numbers involved.
Transcript: Full conversation text with per-message metadata like tone, emotion, and language.
Summaries: Both a detailed full summary and a concise short summary.
Recording: A direct URL to the audio recording of the call.
Data Collected: Structured fields extracted by the AI (e.g., budget, preferences, dates).
Evaluation Results: AI quality checks (e.g., "Was the goal met?", "Did the agent mention pricing?").
Generated Tasks: To-do items automatically created based on the conversation.

Security

To ensure that the data you receive is actually from SkipCalls, we recommend using signature verification:

If a secret is configured, every request will include an X-Webhook-Signature header.
This signature is an HMAC-SHA256 hash of the raw request body, created using your webhook secret.
Your server should calculate the hash and compare it to the header value before processing the data.

Retry Logic

If your server is down or returns an error (anything outside the 200-299 range), SkipCalls will automatically retry the delivery:

3 Retries: We attempt to redeliver the message up to 3 times.
Exponential Backoff: Retries happen after 1s, 2s, and 4s to give your system time to recover.

Testing Tips

Use webhook.site to quickly see the payload structure without writing any code.
Verify that your endpoint responds with a 200 OK status code.
If using a secret, double-check your signature calculation logic if verification fails.

Troubleshooting

Not receiving webhooks? Check if the webhook status is "Active" and verify your URL is publicly accessible.
Signature mismatch? Ensure you are using the raw request body for the HMAC calculation and that your secret matches exactly.
Timeout errors? Your server must respond within 10 seconds. If processing takes longer, consider moving it to a background task and responding immediately.

Quick Reference: Headers include Content-Type: application/json and X-Webhook-Signature (if secret is set). Format choices: DEFAULT (nested) or ZAPIER (flat).