Register a webhook

Registers the URL that receives lead events. The URL must be https.

The first PUT is 201 and returns the URL and the signing secret. Later PUTs replace the URL, keep the same secret, and return only the URL. A lost first response is not shown again. Integrations shows the URL and does not show the secret.

Events are not sent for the submit itself. They are sent when a queued lead is accepted (lead.delivered), when status changes (lead.status_changed), and when a queued lead is declined (lead.declined). The account that sent the lead receives the event, and so does each parent account that has a webhook, for leads in that parent’s Leads Sent scope.

Delivery is at least once. A failed POST keeps the same id and is retried after two minutes, up to 8 attempts, without waiting for another lead. Verify the signature over the raw body before trusting the JSON.

PUT/api/webhooks

Authorization

X-CM-API-KEYAPI key · headerrequired

Account key from Integrations. Keys use the cm_ prefix.

Request body

requiredapplication/json

urlstring<uri>required

Must be an https URL.

Responses

200

The URL was replaced. The signing secret is unchanged and is not returned.

urlstringrequired

201

The webhook was created. Store the secret. It is not shown again.

urlstringrequired

secretstringrequired

Signing secret. Returned only on the first PUT.

401

The key is missing or unknown.

errorstringrequired

403

The key cannot send leads.

errorstringrequired

422

The body is invalid, or the URL is not https.

errorstringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Bodyapplication/json

urlstring*Must be an `https` URL.

Request

curl -X PUT 'https://www.comarketing.com/api/webhooks' \
  -H 'X-CM-API-KEY: YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/hooks"
}'

const response = await fetch("https://www.comarketing.com/api/webhooks", {
  method: "PUT",
  headers: {
    "X-CM-API-KEY": "YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"url\": \"https://example.com/hooks\"\n}"
});

import requests

response = requests.put(
    "https://www.comarketing.com/api/webhooks",
    headers={
        "X-CM-API-KEY": "YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"url\": \"https://example.com/hooks\"\n}",
)

Response

{
  "url": "https://example.com/hooks"
}

{
  "url": "https://example.com/hooks",
  "secret": "signing_secret"
}

{
  "error": "Invalid API key."
}

{
  "error": "This key cannot send leads."
}

{
  "error": "url must be an https URL."
}