Skip to content
Developers

Endpoints

Webhooks

Subscribe a URL to workspace events. This is what the Make instant triggers call when a scenario is turned on and off.

How webhooks work

Webhooks send an event to your URL when something happens in the workspace: a new contact, a booking, a paid order, a finished call. Each delivery is signed so you can check it came from Entagl.

Set up an endpoint

Create an endpoint with POST /webhooks. Pick event types from the list below (or GET /events), or use a wildcard such as contact.* or *. The response includes the signing secret once: store it. The Entagl app for Make does this for you when a scenario with an Entagl trigger is turned on, and deletes the endpoint when it is turned off.

Request
curl -X POST "https://api.entagl.com/api/v1/webhooks" \
  -H "Authorization: Bearer ai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/entagl/webhooks",
    "events": ["contact.created", "booking.*"],
    "description": "CRM sync"
  }'

The webhook you can set up on the Channels → Webhooks page in the app uses the original format: the body is { event, workspace_id, occurred_at, data } and X-Entagl-Signature is sha256= followed by an HMAC-SHA256 of the raw body. Everything below describes endpoints created through the API.

Event format

Each delivery is a POST with a JSON event. type says what happened and data holds the details for that type (see the event list). actor says who caused it (ai, human, customer, system, api, import or provider) and source.connection_id which credential, so an integration can ignore its own changes. Update events also carry changes with the changed field names.

contact.created
{
  "id": "evt_5c1f0a9e7b2d4e3f8a6c0b1d2e3f4a5b",
  "object": "event",
  "type": "contact.created",
  "api_version": "2026-10-01",
  "occurred_at": "2026-10-01T14:32:11.482Z",
  "created_at": "2026-10-01T14:32:11.482Z",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "actor": {
    "type": "api",
    "id": "user_9f2c1a"
  },
  "resource": {
    "type": "contact",
    "id": "6789"
  },
  "source": {
    "connection_id": "apikey:42",
    "via": "api"
  },
  "data": {
    "contact_id": 6789,
    "name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+15551234567",
    "email": "jane@example.com",
    "channel": "instagram",
    "tags": [
      "vip",
      "botox"
    ],
    "stage": {
      "funnel_id": 3,
      "stage_id": 14,
      "stage_name": "Qualified"
    },
    "assigned_to_user_id": "user_9f2c1a",
    "language": "en",
    "custom_fields": {
      "budget": "500-1000",
      "preferred_branch": "Downtown"
    },
    "created_at": "2026-09-28T10:02:44.000Z",
    "updated_at": "2026-10-01T14:32:11.482Z"
  },
  "changes": null
}
  • Content-Typeapplication/json
  • User-AgentEntagl-Webhooks/2.0
  • X-Entagl-SignatureSignature, see below.
  • X-Entagl-Event-IdThe event id. Use it to skip duplicates.
  • X-Entagl-Event-TypeThe event type, e.g. contact.created.
  • X-Entagl-Delivery-Attempt1 on the first try, then 2, 3 …

Verify the signature

The X-Entagl-Signature header looks like t=1767225600,v1=5257a869…. t is the send time in Unix seconds. Each v1 is an HMAC-SHA256, in hex, of the text {t}.{raw body} made with your endpoint secret. Compute it yourself and compare in constant time. Reject the request when t is more than 5 minutes away from your clock. After a secret rotation there are two v1 values for 24 hours: accept the request if either matches.

Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';

const app = express();
// The secret returned once by POST /api/v1/webhooks (or by rotate-secret).
const SECRET = process.env.ENTAGL_WEBHOOK_SECRET;

// Read the RAW body: the signature covers the exact bytes Entagl sent.
app.post('/entagl/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verifyEntaglSignature(req.get('X-Entagl-Signature') || '', rawBody, SECRET)) {
    return res.status(400).send('invalid signature');
  }
  const event = JSON.parse(rawBody);
  // Deliveries can repeat: skip an event.id you have already handled.
  console.log(event.type, event.id);
  res.sendStatus(200); // any 2xx within 10 seconds counts as delivered
});

function verifyEntaglSignature(header, rawBody, secret, toleranceSeconds = 300) {
  const parts = header.split(',').map((p) => p.trim());
  const t = Number(parts.find((p) => p.startsWith('t='))?.slice(2));
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return parts
    .filter((p) => p.startsWith('v1='))
    .some((p) => {
      const got = p.slice(3);
      return got.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
    });
}

app.listen(3000);

Delivery and retries

  • Answer with any 2xx status within 10 seconds. Redirects are not followed.
  • Anything else is a failed attempt. Entagl retries after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours, then marks the delivery failed (7 attempts in all).
  • 410 Gone stops the retries at once and disables the endpoint.
  • An endpoint that keeps failing for 72 hours is disabled and the workspace owner is notified. Turn it back on with PATCH /webhooks/:id and "status": "active".
  • A delivery can arrive more than once, and events can arrive out of order. Use the event id to skip duplicates.
  • GET /webhooks/:id/deliveries shows the last 30 days of attempts; POST …/redeliver sends one again.

Privacy

By default, events leave out what customers wrote (message text, transcripts, summaries, notes) and their contact details (names, phones, emails, usernames). The event list shows these fields for each event. To receive them, set include_content and/or include_contact_details on the endpoint. Only a workspace owner or admin can turn them on. On HIPAA workspaces they are never sent, whatever the settings. When a private field is left out, changes still lists its name but never its old value.

Event list

Every event type Entagl sends today. message.received and message.sent are high volume: a wildcard never includes them, so list them by name. GET /events returns the same catalog as JSON.

Contacts (11)

contact.createdContact created

Fires when a new contact is added: a first message from someone new, a manual add, an import or the API.

Contact detail fields:namefirst_namelast_namephoneemailcustom_fields

contact.updatedContact updated

Fires when any contact field or custom field changes. The envelope "changes" lists the changed fields and their previous values.

Contact detail fields:namefirst_namelast_namephoneemailcustom_fields

contact.deletedContact deleted

Fires when a contact is deleted. Carries ids only.

contact.tag_addedContact tag added

Fires when one or more tags are added to a contact.

contact.tag_removedContact tag removed

Fires when one or more tags are removed from a contact.

contact.stage_changedLifecycle stage changed

Fires when a contact moves to another funnel stage, or the stage is removed.

contact.assignedContact owner changed

Fires when a contact is assigned to a team member or unassigned.

contact.lead_capturedLead captured

Fires when the AI (or a form) marks a contact as a lead, with a short summary of what they want.

Content fields:summary

Contact detail fields:namephoneemail

contact.mergedContacts merged

Fires when two contacts are merged into one. The secondary contact id now redirects to the primary.

contact.opted_outContact opted out

Fires when a contact is marked do-not-contact or opts out of marketing messages.

note.createdContact note added

Fires when a team member adds a note to a contact.

Content fields:body

Conversations (7)

conversation.createdConversation opened

Fires when a new conversation starts on any channel.

conversation.reopenedConversation reopened

Fires when a closed conversation is opened again, by a new customer message or a team member.

conversation.closedConversation closed

Fires when a conversation is closed by a team member, the API or auto-close, with the closing note if any.

Content fields:closing_note_text

conversation.assignedConversation assignee changed

Fires when a conversation is assigned to a team member or unassigned.

conversation.ai_pausedAI paused on a conversation

Fires when AI replies are paused on a conversation (team member takeover, handover, spam, schedule or API).

conversation.ai_resumedAI resumed on a conversation

Fires when AI replies are switched back on for a conversation.

conversation.comment_createdConversation comment added

Fires when a team member (or the API) adds an internal comment to a conversation. Customers never see comments.

Content fields:body

Messages (3)

message.receivedIncoming message
High volume: subscribe by name

Fires for every message a customer sends, on any channel. High volume — subscribe only if you need every message.

Content fields:text

message.sentOutgoing message
High volume: subscribe by name

Fires for every message sent to a customer: AI replies, team replies, campaigns and automations.

Content fields:text

message.send_failedMessage failed to send

Fires when a message to a customer could not be delivered by the channel.

Handovers (2)

handover.requestedHandover requested

Fires when the AI hands a conversation to a human (customer asked for a person, complaint, or a question it could not answer).

Content fields:summary

Contact detail fields:customer_namecustomer_phone

handover.resolvedHandover resolved

Fires when a team member (or auto-resolve) marks a handover as handled.

AI (3)

conversation.followup_sentFollow-up sent

Fires when the AI sends an automatic follow-up to a customer who went quiet.

ai_turn.failedAI reply failed

Fires when the AI could not produce a reply for a customer message (a fallback message may have been sent instead).

message_feedback.submittedAI reply rated

Fires when a team member gives thumbs up or down to an AI reply.

Content fields:comment

Bookings (6)

booking.createdBooking created

Fires when an appointment is created for a customer.

Content fields:conversation_summarydocuments

Contact detail fields:customer_namecustomer_phone

booking.documents.addedBooking documents added

Fires when a customer shares a document or photo in a conversation after their booking was created. Delivers only the new file(s).

Content fields:documents

Contact detail fields:customer_namecustomer_phone

booking.updatedBooking updated

Fires when any booking detail changes (time, service, duration, location, notes). The envelope "changes" lists what changed.

Contact detail fields:customer_namecustomer_phone

booking.rescheduledBooking rescheduled

Fires when a booking moves to a new date or time.

Contact detail fields:customer_namecustomer_phone

booking.cancelledBooking cancelled

Fires when a booking is cancelled by the customer (through the AI), a team member, or the API.

Contact detail fields:customer_namecustomer_phone

booking.status_changedBooking status changed

Fires when a booking status changes, e.g. confirmed, completed or no-show.

Contact detail fields:customer_namecustomer_phone

Reminders (4)

reminder.createdReminder created

Fires when a reminder is created.

Content fields:titlenote

reminder.firedReminder due

Fires when a reminder becomes due and the assignees are notified.

Content fields:titlenote

reminder.closedReminder closed

Fires when a reminder is marked done.

Content fields:titlenote

appointment_reminder.sentAppointment reminder sent

Fires when an automatic appointment reminder (WhatsApp template or SMS) is sent to a customer.

Orders (6)

order.createdOrder created

Fires when an order is created by the AI, a team member, a store sync or the API.

Contact detail fields:customer_namecustomer_phone

order.updatedOrder updated

Fires when any order detail or item changes. The envelope "changes" lists what changed.

Contact detail fields:customer_namecustomer_phone

order.status_changedOrder status changed

Fires when an order status changes (for example confirmed, shipped, delivered).

Contact detail fields:customer_namecustomer_phone

order.paidOrder paid

Fires when an order is marked as paid.

Contact detail fields:customer_namecustomer_phone

order.cancelledOrder cancelled

Fires when an order is cancelled.

Contact detail fields:customer_namecustomer_phone

order.payment_proof_uploadedPayment proof uploaded

Fires when a customer (through the AI) or a team member attaches a payment receipt to an order.

Products (3)

product.createdProduct created

Fires when a product is added to the catalog.

product.updatedProduct updated

Fires when a product changes (price, stock, details).

product.deletedProduct deleted

Fires when a product is removed from the catalog.

Calls (3)

call.endedCall ended

Fires after every AI phone or WhatsApp call, with outcome and (opt-in) summary and transcript.

Content fields:summarytranscript

Contact detail fields:from_numberto_number

call.missedMissed call

Fires when an incoming call was not answered or an outgoing call got no answer.

Content fields:summarytranscript

Contact detail fields:from_numberto_number

call.voicemail_receivedVoicemail received

Fires when a caller leaves a voicemail.

Content fields:transcript_text

Contact detail fields:from_number

Campaigns (3)

campaign.completedCampaign finished sending

Fires when a broadcast campaign finished sending to all recipients.

campaign_recipient.repliedCampaign reply

Fires when a recipient replies to a campaign message.

campaign_recipient.failedCampaign message failed

Fires when a campaign message could not be delivered to a recipient.

Forms (1)

form.submittedForm submitted

Fires when a customer submits a form (website widget, hosted link or in-chat intake).

Content fields:fields

Account (3)

channel.disconnectedChannel disconnected

Fires when a channel stops working (token expired, access removed) or is disconnected.

channel.reconnectedChannel healthy again

Fires when a previously failing channel works again.

credits.threshold_reachedCredits running low

Fires when credit usage crosses 80%, 100% or 120% of the plan allowance.

Workspace (3)

tag.createdTag created

Fires when a tag is added to the workspace tag list.

tag.updatedTag updated

Fires when a workspace tag is renamed or recolored.

tag.deletedTag deleted

Fires when a workspace tag is deleted (it is removed from every contact).

Paths are relative to the base URL. Each card lists the permission the call needs and every parameter, with its type and limits.

GET
/webhooks

List webhook endpoints.

Permission: integrations
Paginated
POST
/webhooks

Create a webhook endpoint. The signing secret is returned once, in this response.

Permission: integrations

JSON body

  • urlrequiredstring (URL)

    https:// URL that receives events, up to 2,048 characters. Private and internal addresses are refused (422 unsafe_url).

  • eventsrequiredarray of strings

    1–100 event types from GET /events, "<prefix>.*" (e.g. "contact.*") or "*". Wildcards never include message.received and message.sent; list those explicitly.

  • descriptionoptionalstring

    Up to 200 characters.

  • filtersoptionalobject

    Optional narrowing: channels (array of channel names, up to 20), actor_types (array, up to 7), sources (object of event type → source keys), ignore_own_changes (boolean — skip events caused by this same connection; on by default for connector-created endpoints).

  • include_contentoptionalboolean

    Include message text, transcripts and notes. Owner or admin only; refused on HIPAA workspaces.

  • include_contact_detailsoptionalboolean

    Include names, phones, emails and handles. Owner or admin only; refused on HIPAA workspaces.

  • created_viaoptionalenum

    Which tool created the endpoint.

    Allowed values:apimakezapiern8n

  • A workspace can have up to 100 endpoints (409 endpoint_limit_reached).
GET
/webhooks/:id

Retrieve a webhook endpoint with its status and last delivery result.

Permission: integrations

Path parameters

  • idrequiredstring

    Endpoint ID (starts with "we_").

PATCH
/webhooks/:id

Update an endpoint, or pause and re-activate it.

Permission: integrations

Path parameters

  • idrequiredstring

    Endpoint ID.

JSON body

  • urloptionalstring (URL)

    New receiving URL.

  • eventsoptionalarray of strings

    New event list.

  • descriptionoptionalstring | null

    Up to 200 characters.

  • filtersoptionalobject

    Optional narrowing: channels (array of channel names, up to 20), actor_types (array, up to 7), sources (object of event type → source keys), ignore_own_changes (boolean — skip events caused by this same connection; on by default for connector-created endpoints).

  • include_contentoptionalboolean

    Owner or admin only to turn on.

  • include_contact_detailsoptionalboolean

    Owner or admin only to turn on.

  • statusoptionalenum

    Re-activating resets the failure count.

    Allowed values:activepaused

  • On an endpoint that includes content or contact details, only an owner or admin can change url, events or filters.
DELETE
/webhooks/:id

Delete an endpoint (a Make trigger calls this when its scenario is turned off).

Permission: integrations

Path parameters

  • idrequiredstring

    Endpoint ID.

POST
/webhooks/:id/rotate-secret

Issue a new signing secret. The previous secret keeps signing deliveries for 24 hours.

Permission: integrations

Path parameters

  • idrequiredstring

    Endpoint ID.

POST
/webhooks/:id/test

Send a signed sample event to the endpoint now and return the result (delivered, status, error, duration_ms).

Permission: integrations

Path parameters

  • idrequiredstring

    Endpoint ID.

JSON body

  • eventoptionalstring

    Event type to sample. Defaults to the endpoint's first non-wildcard event, else a generic "webhook.test" event.

GET
/webhooks/:id/deliveries

Recent delivery attempts, newest first. Deliveries are kept for 30 days.

Permission: integrations
Paginated

Path parameters

  • idrequiredstring

    Endpoint ID.

POST
/webhooks/:id/deliveries/:deliveryId/redeliver

Queue a delivery to be sent again. Answers 202.

Permission: integrations

Path parameters

  • idrequiredstring

    Endpoint ID.

  • deliveryIdrequiredinteger

    Delivery ID from the deliveries list.