GoliathDevelopersGet an API key
Webhooks / Overview

Overview

Per-organization HTTP endpoints that let external systems create or update contacts in Goliath without a user JWT.

Inbound webhooks give you a stable URL you can call from any external system — Airtable, Zapier, a custom CRM, a dialer — to push contact data directly into Goliath. No user session required.

How it works

  1. An org admin creates a webhook in Settings → Integrations → Webhooks
  2. Goliath generates a unique token and returns a full URL
  3. You POST JSON to that URL to create, find, or update contacts
  4. Goliath processes the request — some endpoints are synchronous, others are queued asynchronously

Base URL shape

{WEBHOOK_BASE_URL}/{token}/contacts/{action}
  • WEBHOOK_BASE_URL is environment-specific. The full URL is shown in the product after creation.
  • token is a UUID that identifies and authenticates your webhook
  • Everything after the token is the action path (e.g. /contacts/create-with-ai)

Endpoints

Path Mode Description
contacts/create-with-ai Async AI extraction — best for unstructured text
contacts/create Async Structured create — use when data is already clean
contacts/find Sync Search contacts by name, phone, or email
contacts/update Sync Patch an existing contact by ID

Async vs sync

Two of the endpoints return immediately and queue work in the background. Two run synchronously and return results inline.

Mode Endpoints What you get back
Async create-with-ai, create { success, acknowledged, eventId } — contact may not exist yet
Sync find, update Full result or updated contact ID inline

Managing webhooks

Action Who How
Create Org admin only Settings → Integrations → Webhooks → Set Up
List Any org member Settings → Integrations → Webhooks — non-admins see the label but not the URL
Enable / disable Org admin Toggle active state — inactive tokens return 401
Delete Org admin Removes the token permanently

Authentication

See Authentication for full details on token auth and the alternative JWT path.

Security

  • Treat the full webhook URL as a secret. It is bearer-equivalent — anyone with the URL can call it.
  • The URL may appear in proxy logs, browser network panels, and third-party request logs. Rotate the token if it is exposed.
  • Tokens are org-scoped. A token from one org cannot access another org’s data.