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.
Each webhook URL is scoped to a single organization. The token embedded in the URL is the only credential required.
How it works
- An org admin creates a webhook in Settings → Integrations → Webhooks
- Goliath generates a unique token and returns a full URL
- You
POST JSON to that URL to create, find, or update contacts
- 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 |
contacts/unstructured is a deprecated alias for contacts/create-with-ai. It still works but should not be used in new integrations.
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 |
A 200 response on an async endpoint means the request was accepted and queued — not that the contact has been created. Do not immediately query for the contact after a create call.
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 |
lastUsedAt is updated on every successful authenticated request. You can use this to audit whether an integration is active.
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.
