Skip to main content
POST
/
v2
/
webhooks
Create Webhook
curl --request POST \
  --url https://api.example.com/v2/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "account_id": "<string>",
  "url": "<string>",
  "events": [
    {}
  ]
}
'
{
  "success": true,
  "data": {
    "webhook_id": "6789abcdef0123456789abcd",
    "account_id": "69c127c37cae0494dd827286",
    "mode": "hosted",
    "stream_url": "/v2/webhooks/6789abcdef0123456789abcd/stream",
    "events_url": "/v2/webhooks/6789abcdef0123456789abcd/events",
    "events": ["accepted_invitation", "message_received"],
    "is_active": true
  },
  "metadata": {
    "action": "create_webhook",
    "credits_consumed": 0,
    "timestamp": "2025-01-15T10:30:00.000000"
  }
}
Create a webhook listener for one of your connected accounts. The delivery mode is determined by whether you provide a url:
  • With url — Custom mode: events are sent as POST requests to your URL
  • Without url — Hosted mode: events are available via SSE stream or polling
Monitoring starts automatically. As soon as the webhook is created, the account’s real-time SSE stream is opened and credit billing begins (≈10 credits/day per account). You don’t need to call /start — that endpoint is only used to resume a webhook that was previously stopped via /stop.Calling POST /v2/webhooks itself costs 0 credits; the running cost comes from the live monitoring it enables.

​
Header Parameters

​
x-api-key
string
required
Your API key

​
Body Parameters

​
account_id
string
required
The ID of the account to monitor. Must be an account you own (created via /v2/login).
​
url
string
The URL where events will be sent as POST requests. Must be a publicly accessible HTTPS endpoint.Omit this field to create a hosted webhook (SSE/polling).
​
events
array
default:"[\"all\"]"
List of event types to listen for. Defaults to ["all"] which receives every event.Available event types: message_received, accepted_invitation, all.

​
Response

​
success
boolean
Whether the webhook was created successfully
​
data
object
{
  "success": true,
  "data": {
    "webhook_id": "6789abcdef0123456789abcd",
    "account_id": "69c127c37cae0494dd827286",
    "mode": "hosted",
    "stream_url": "/v2/webhooks/6789abcdef0123456789abcd/stream",
    "events_url": "/v2/webhooks/6789abcdef0123456789abcd/events",
    "events": ["accepted_invitation", "message_received"],
    "is_active": true
  },
  "metadata": {
    "action": "create_webhook",
    "credits_consumed": 0,
    "timestamp": "2025-01-15T10:30:00.000000"
  }
}

​
Notes

  • The webhook is created in an active and monitoring state — events start flowing immediately, no extra call required.
  • You can create multiple webhooks for the same account with different event filters. Billing is per-account (not per-webhook), so adding a second webhook to the same account doesn’t double the credit cost.
  • Stopping the last active webhook on an account (via /stop or DELETE) halts monitoring and stops the credit billing automatically. Other webhooks on the same account are unaffected.
  • For custom mode, the webhook URL must return a 200 status code to acknowledge receipt.
  • When accepted_invitation is in the events list, the API performs an initial sync of your connections to enable detection of new acceptances.