> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  Each webhook URL is scoped to a single organization. The token embedded in the URL is the only credential required.
</Note>

***

## 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                    |

<Note>
  `contacts/unstructured` is a deprecated alias for `contacts/create-with-ai`. It still works but should not be used in new integrations.
</Note>

***

## 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                         |

<Warning>
  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.
</Warning>

***

## 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                                                 |

<Note>
  `lastUsedAt` is updated on every successful authenticated request. You can use this to audit whether an integration is active.
</Note>

***

## Authentication

See [Authentication](/webhooks/inbound/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.