How to Use Call Webhooks & API for Automation

If you record and analyze sales or support calls, the data is only useful when it reaches the systems your team actually works in. Manually exporting transcripts or copy-pasting QA scores into a CRM does not scale. The fix is a two-part automation pattern: webhooks to react instantly when something happens, and a REST API to read the data when you need it. This guide explains how both work, when to use each, and how to wire them up safely.

Webhooks vs. API: which one for which job

People often confuse the two, but they solve opposite problems.

• Webhooks are push. Your call platform sends an HTTP POST to a URL you control the moment an event occurs — a recording finished, a transcript is ready, or a QA analysis completed. You react in real time, no polling required.
• The API is pull. Your code makes a request whenever you need data — list recent calls, fetch one call's full score breakdown, or sync history into a warehouse on a schedule.

A good rule of thumb: use webhooks to trigger a workflow, and the API to fetch the details. The webhook says "call 12345 was just scored 82/100"; your handler then calls the API to retrieve the criteria, strengths, and issues before writing them to HubSpot or Salesforce.

Step 1: Set up an outbound webhook

In most platforms you register a webhook by giving it three things: a destination URL (must be HTTPS and publicly reachable), the events you care about, and an optional signing secret. In MeetGrade, for example, you can register an outbound webhook on the qa_completed event. When a call's analysis finishes, it POSTs a compact JSON payload to your endpoint with fields like bot_id, source (zoom / meet / phone), manager_email, score, key_result_achieved, checklist_id, and a direct call_url link back to the recording.

Your endpoint should do three things and nothing more: verify the signature, return a 2xx status quickly, and hand the work to a background job. Long processing inside the handler causes timeouts and unnecessary retries.

Step 2: Verify the signature

An exposed webhook URL is a public endpoint — anyone who finds it could POST fake events. Always verify authenticity before trusting a payload. The standard approach is HMAC-SHA256: the sender computes a hash of the raw request body using your shared secret and sends it in a header.

MeetGrade signs the body and sends it as X-StudyLess-Signature: sha256=<hex>, with the event name in X-StudyLess-Event. On your side, recompute the HMAC over the exact raw bytes you received (not a re-serialized version — whitespace and key order matter) and compare using a constant-time check. If it does not match, return 401 and drop the request. Never log the secret.

Step 3: Handle retries and ordering

Networks fail, and well-behaved senders retry. A common pattern — and the one MeetGrade uses — is to retry only on 5xx and network errors with exponential backoff (typically up to 3 attempts), and to not retry on 4xx, since a client error means the request itself is wrong. Two consequences for your design:

• Be idempotent. The same event may arrive more than once. Key your processing on a stable identifier (like bot_id + event) so a duplicate delivery does not create a duplicate CRM note.
• Do not assume strict ordering. If order matters, use timestamps in the payload rather than arrival order.

Step 4: Pull details with the REST API

Once a webhook tells you a call is ready, fetch the full record over the API. MeetGrade exposes a read-only /api/v1/ REST API authenticated with a per-organization Bearer token (format mg_live_<keyid>_<secret>). Core endpoints:

• GET /api/v1/calls — a paginated list of your organization's calls (supports limit and offset).
• GET /api/v1/calls/{bot_id} — one call with its full QA object: per-criterion scores, total score, summary, strengths, and issues.
• GET /api/v1/checklists — your scoring checklists (id, name, version, criteria labels).

Keys are scoped to a single tenant, so the API only ever returns your own data. Expect rate limits (e.g. 120 requests per minute per key) and a 429 when you exceed them — batch your reads and respect backoff.

Real automations you can build

• CRM sync: on qa_completed, write the score and a summary note to the matching contact or deal in HubSpot, Salesforce, Pipedrive, or a CRM like Leeloo.
• Coaching alerts: if key_result_achieved is false or the score drops below a threshold, post to a Slack channel so a manager can review the call.
• Hiring / interview review: route completed interview analyses into your ATS as evidence-based, competency-level decision support — structured signals tied to your checklist, not lie-detection or facial-emotion reading.
• Analytics: on a schedule, pull GET /calls into a warehouse (BigQuery, Snowflake) for talk-ratio and trend dashboards.

Quick checklist before you ship

• Endpoint is HTTPS and returns 2xx fast; heavy work is offloaded.
• Signature verified with constant-time comparison on the raw body.
• Processing is idempotent and tolerant of out-of-order delivery.
• API calls use a secret-stored Bearer key and handle 429 / pagination.

Webhooks plus a clean REST API turn call recordings from a static archive into a live data source your whole stack can react to. If you want a platform where the QA scoring, talk metrics, outbound webhooks, and a per-tenant API ship together — and pricing is pay-as-you-go — MeetGrade is worth a look as one option to prototype your first automation against.