Endpoints

Webhooks

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

Πώς λειτουργούν τα webhooks

Τα webhooks στέλνουν ένα event στο URL σας όταν συμβαίνει κάτι στο workspace: μια νέα επαφή, μια κράτηση, μια πληρωμένη παραγγελία, μια ολοκληρωμένη κλήση. Κάθε παράδοση είναι υπογεγραμμένη, ώστε να ελέγχετε ότι προέρχεται από το Entagl.

Ρυθμίστε ένα endpoint

Δημιουργήστε ένα endpoint με POST /webhooks. Διαλέξτε τύπους event από την παρακάτω λίστα (ή από το GET /events), ή χρησιμοποιήστε ένα wildcard όπως contact.* ή *. Η απόκριση περιλαμβάνει το secret υπογραφής μία μόνο φορά: αποθηκεύστε το. Η εφαρμογή Entagl για το Make το κάνει αυτό για εσάς όταν ενεργοποιείται ένα scenario με Entagl trigger, και διαγράφει το endpoint όταν απενεργοποιείται.

Αίτημα

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"
  }'

Το webhook που ρυθμίζετε στη σελίδα Κανάλια → Webhooks της εφαρμογής χρησιμοποιεί την αρχική μορφή: το σώμα είναι { event, workspace_id, occurred_at, data } και το X-Entagl-Signature είναι sha256= ακολουθούμενο από ένα HMAC-SHA256 του ωμού σώματος. Όλα όσα ακολουθούν περιγράφουν endpoints που δημιουργούνται μέσω του API.

Μορφή του event

Κάθε παράδοση είναι ένα POST με ένα event JSON. Το type λέει τι συνέβη και το data περιέχει τις λεπτομέρειες για αυτόν τον τύπο (δείτε τη λίστα events). Το actor λέει ποιος το προκάλεσε (ai, human, customer, system, api, import ή provider) και το source.connection_id ποιο διαπιστευτήριο, ώστε μια ενσωμάτωση να αγνοεί τις δικές της αλλαγές. Τα events ενημέρωσης φέρουν επίσης το changes με τα ονόματα των πεδίων που άλλαξαν.

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-SignatureΥπογραφή, δείτε παρακάτω.
X-Entagl-Event-IdΤο ID του event. Χρησιμοποιήστε το για να παραλείπετε διπλότυπα.
X-Entagl-Event-TypeΟ τύπος του event, π.χ. contact.created.
X-Entagl-Delivery-Attempt1 στην πρώτη προσπάθεια, μετά 2, 3 …

Επαληθεύστε την υπογραφή

Το header X-Entagl-Signature μοιάζει με t=1767225600,v1=5257a869…. Το t είναι η ώρα αποστολής σε δευτερόλεπτα Unix. Κάθε v1 είναι ένα HMAC-SHA256, σε hex, του κειμένου {t}.{raw body} που δημιουργείται με το secret του endpoint σας. Υπολογίστε το μόνοι σας και συγκρίνετε σε σταθερό χρόνο. Απορρίψτε το αίτημα όταν το t απέχει πάνω από 5 λεπτά από το ρολόι σας. Μετά από εναλλαγή (rotation) του secret υπάρχουν δύο τιμές v1 για 24 ώρες: δεχτείτε το αίτημα αν ταιριάζει οποιαδήποτε από τις δύο.

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);

Παράδοση και επαναλήψεις

Απαντήστε με οποιονδήποτε κωδικό 2xx μέσα σε 10 δευτερόλεπτα. Οι ανακατευθύνσεις δεν ακολουθούνται.
Οτιδήποτε άλλο είναι αποτυχημένη προσπάθεια. Το Entagl ξαναδοκιμάζει μετά από 30 δευτερόλεπτα, 2 λεπτά, 10 λεπτά, 1 ώρα, 6 ώρες και 24 ώρες, και μετά σημειώνει την παράδοση ως αποτυχημένη (7 προσπάθειες συνολικά).
Το 410 Gone σταματά αμέσως τις επαναλήψεις και απενεργοποιεί το endpoint.
Ένα endpoint που αποτυγχάνει συνεχώς για 72 ώρες απενεργοποιείται και ειδοποιείται ο ιδιοκτήτης του workspace. Ενεργοποιήστε το ξανά με PATCH /webhooks/:id και "status": "active".
Μια παράδοση μπορεί να φτάσει περισσότερες από μία φορές και τα events μπορεί να φτάσουν εκτός σειράς. Χρησιμοποιήστε το ID του event για να παραλείπετε διπλότυπα.
Το GET /webhooks/:id/deliveries δείχνει τις προσπάθειες των τελευταίων 30 ημερών. Το POST …/redeliver στέλνει ξανά μία.

Απόρρητο

Από προεπιλογή, τα events παραλείπουν ό,τι έγραψαν οι πελάτες (κείμενο μηνυμάτων, μεταγραφές, περιλήψεις, σημειώσεις) και τα στοιχεία επικοινωνίας τους (ονόματα, τηλέφωνα, emails, usernames). Η λίστα events δείχνει αυτά τα πεδία για κάθε event. Για να τα λαμβάνετε, ορίστε include_content ή/και include_contact_details στο endpoint. Μόνο ο ιδιοκτήτης ή ένας admin του workspace μπορεί να τα ενεργοποιήσει. Στα workspaces HIPAA δεν στέλνονται ποτέ, ανεξάρτητα από τις ρυθμίσεις. Όταν ένα ιδιωτικό πεδίο παραλείπεται, το changes εξακολουθεί να καταγράφει το όνομά του, αλλά ποτέ την παλιά τιμή του.

Λίστα events

Κάθε τύπος event που στέλνει σήμερα το Entagl. Τα message.received και message.sent έχουν μεγάλο όγκο: ένας χαρακτήρας μπαλαντέρ (wildcard) δεν τα περιλαμβάνει ποτέ, γι' αυτό δηλώστε τα με το όνομά τους. Το GET /events επιστρέφει τον ίδιο κατάλογο ως 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.

Πεδία στοιχείων επαφής: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.

Πεδία στοιχείων επαφής: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.

Πεδία περιεχομένου:summary

Πεδία στοιχείων επαφής: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.

Πεδία περιεχομένου: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.

Πεδία περιεχομένου: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.

Πεδία περιεχομένου:body

Messages (3)

message.receivedIncoming message

Μεγάλος όγκος: εγγραφή με το όνομα

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

Πεδία περιεχομένου:text

message.sentOutgoing message

Μεγάλος όγκος: εγγραφή με το όνομα

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

Πεδία περιεχομένου: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).

Πεδία περιεχομένου:summary

Πεδία στοιχείων επαφής: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.

Πεδία περιεχομένου:comment

Bookings (6)

booking.createdBooking created

Fires when an appointment is created for a customer.

Πεδία περιεχομένου:conversation_summarydocuments

Πεδία στοιχείων επαφής: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).

Πεδία περιεχομένου:documents

Πεδία στοιχείων επαφής:customer_namecustomer_phone

booking.updatedBooking updated

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

Πεδία στοιχείων επαφής:customer_namecustomer_phone

booking.rescheduledBooking rescheduled

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

Πεδία στοιχείων επαφής:customer_namecustomer_phone

booking.cancelledBooking cancelled

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

Πεδία στοιχείων επαφής:customer_namecustomer_phone

booking.status_changedBooking status changed

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

Πεδία στοιχείων επαφής:customer_namecustomer_phone

Reminders (4)

reminder.createdReminder created

Fires when a reminder is created.

Πεδία περιεχομένου:titlenote

reminder.firedReminder due

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

Πεδία περιεχομένου:titlenote

reminder.closedReminder closed

Fires when a reminder is marked done.

Πεδία περιεχομένου: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.

Πεδία στοιχείων επαφής:customer_namecustomer_phone

order.updatedOrder updated

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

Πεδία στοιχείων επαφής:customer_namecustomer_phone

order.status_changedOrder status changed

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

Πεδία στοιχείων επαφής:customer_namecustomer_phone

order.paidOrder paid

Fires when an order is marked as paid.

Πεδία στοιχείων επαφής:customer_namecustomer_phone

order.cancelledOrder cancelled

Fires when an order is cancelled.

Πεδία στοιχείων επαφής: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.

Πεδία περιεχομένου:summarytranscript

Πεδία στοιχείων επαφής:from_numberto_number

call.missedMissed call

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

Πεδία περιεχομένου:summarytranscript

Πεδία στοιχείων επαφής:from_numberto_number

call.voicemail_receivedVoicemail received

Fires when a caller leaves a voicemail.

Πεδία περιεχομένου:transcript_text

Πεδία στοιχείων επαφής: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).

Πεδία περιεχομένου: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).

Οι διαδρομές είναι σχετικές με το βασικό URL. Κάθε κάρτα δείχνει το δικαίωμα που απαιτεί η κλήση και κάθε παράμετρο, με τον τύπο και τα όριά της.

GET

/webhooks

List webhook endpoints.

Δικαίωμα: integrations

Με σελιδοποίηση

POST

/webhooks

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

Δικαίωμα: integrations

Σώμα JSON

urlυποχρεωτικόstring (URL)
https:// URL that receives events, up to 2,048 characters. Private and internal addresses are refused (422 unsafe_url).
eventsυποχρεωτικόarray 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.
descriptionπροαιρετικόstring
Up to 200 characters.
filtersπροαιρετικόobject
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_contentπροαιρετικόboolean
Include message text, transcripts and notes. Owner or admin only; refused on HIPAA workspaces.
include_contact_detailsπροαιρετικόboolean
Include names, phones, emails and handles. Owner or admin only; refused on HIPAA workspaces.
created_viaπροαιρετικόenum
Which tool created the endpoint.
Επιτρεπτές τιμές: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.

Δικαίωμα: integrations

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID (starts with "we_").

PATCH

/webhooks/:id

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

Δικαίωμα: integrations

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID.

Σώμα JSON

urlπροαιρετικόstring (URL)
New receiving URL.
eventsπροαιρετικόarray of strings
New event list.
descriptionπροαιρετικόstring | null
Up to 200 characters.
filtersπροαιρετικόobject
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_contentπροαιρετικόboolean
Owner or admin only to turn on.
include_contact_detailsπροαιρετικόboolean
Owner or admin only to turn on.
statusπροαιρετικόenum
Re-activating resets the failure count.
Επιτρεπτές τιμές: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).

Δικαίωμα: integrations

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID.

POST

/webhooks/:id/rotate-secret

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

Δικαίωμα: integrations

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID.

POST

/webhooks/:id/test

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

Δικαίωμα: integrations

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID.

Σώμα JSON

eventπροαιρετικόstring
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.

Δικαίωμα: integrations

Με σελιδοποίηση

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID.

POST

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

Queue a delivery to be sent again. Answers 202.

Δικαίωμα: integrations

Παράμετροι διαδρομής

idυποχρεωτικόstring
Endpoint ID.
deliveryIdυποχρεωτικόinteger
Delivery ID from the deliveries list.