Webhooks

Create a webhook

Register a callback URL that Village will POST the user's own Village activity to, as it happens — new connections, job changes among their contacts, new search results, list changes, and sequence-email events. Use this to push activity into a CRM, an automation, or the user's own backend instead of polling. Because this sends the user's relationship data to a third-party endpoint, only register a URL the user has explicitly given you, and read it back to them before creating it. Provide url (publicly reachable http(s), HTTPS recommended; localhost and private IPs are rejected) and optionally event_filter to narrow which events are sent — omit it, or pass null, to receive EVERY event type including ones added later. Deliveries are HMAC-signed; pass your own secret (32+ characters), or omit it and Village generates one. This create response is the ONE place the secret is returned — save it if you intend to verify signatures, because reads only report has_secret, never the value. Returns the webhook with its encrypted id.

post/v2/webhooks

Request

  • Base URL: https://api.village.ai
  • URL: https://api.village.ai/v2/webhooks
  • Auth: HTTP bearer

Request body

urlstring uri required

HTTP(S) endpoint that receives the event payloads (HTTPS recommended). Must be publicly reachable and controlled by the user — localhost and private IP ranges are rejected.

descriptionstring

Human-readable label, so you can tell your webhooks apart later

secretstring

Your own HMAC signing secret (min 32 characters), used to sign every delivery so your endpoint can verify it really came from Village. Leave this out and Village generates one for you; either way the secret is readable via this API.

is_activeboolean

Whether the webhook starts out receiving deliveries

event_filterstring[] nullable

Event types this webhook receives. Pass null (or omit on create) to receive EVERY event type, including ones added in future. Pass an explicit array to narrow it.

Example request

{
  "url": "https://example.com/hooks/village",
  "description": "Notify CRM on new connections",
  "secret": "a-32-character-or-longer-shared-secret",
  "is_active": true,
  "event_filter": [
    "new_connection",
    "job_change"
  ]
}

Response

Webhook created successfully

Example response

{
  "data": {
    "id": "MLVEUadsfgzdsafsc10q5g%3D%3D!vNnNM",
    "event_filter": [
      "new_connection"
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.