خطافات الويب
أحداث العمل تُرسل إلى نقطة HTTPS الخاصة بك، موقّعة ومعادة المحاولة ومسجّلة.
X-Zmle-Signature: sha256=<hmac of timestamp.body>
التوقيع
كل تسليم هو طلب POST بصيغة JSON { id, event, createdAt, data }. تحمل X-Zmle-Timestamp الوقت، وتحمل X-Zmle-Signature القيمة sha256= متبوعة بـ HMAC-SHA256 لـ "timestamp.body" بسر نقطة النهاية. ارفض الطلبات الأقدم من خمس دقائق.
import { createHmac, timingSafeEqual } from "node:crypto";
// headers: X-Zmle-Timestamp, X-Zmle-Signature ("sha256=<hex>"); body: the raw request body (string)
export function verify(secret, timestamp, body, signature) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}إعادة المحاولة
إذا لم تُجب نقطة النهاية برمز 2xx خلال 10 ثوانٍ، يُعاد التسليم حتى 6 مرات بعد 1, 5, 30, 120, 720, 1440 دقيقة. تُوقف نقطة النهاية بعد 25 تسليمًا فاشلًا متتاليًا. كل محاولة مسجلة في سجل التسليم.
التعامل مع التسليمات
- يبقى id نفسه في كل إعادة: احفظه وتجاهل التسليم الذي عالجته من قبل
- قد تصل التسليمات بغير ترتيب: استخدم createdAt، واقرأ السجل من جديد إذا كان الترتيب مهمًا
- أجب بـ 2xx بسرعة ونفّذ العمل بعد ذلك؛ لا تُتبع عمليات إعادة التوجيه
- غيّر السر من صفحة نقطة النهاية في الإدارة ← التكاملات والواجهة البرمجية: يُعرض السر الجديد مرة واحدة ويوقّع كل تسليم بعدها، فحدّث جهة الاستقبال فورًا
المرجع أدناه باللغة الإنجليزية، مثل مستند OpenAPI.
الأحداث
Leads
inquiry.created | A lead arrived from the contact / quote / booking form, the API or WhatsApp. | id, type, name, email, phone, subject, message, source, createdAt |
Quotations
quotation.sent | A quotation was sent to the customer. | id, number, customerName, customerEmail, total, currency, validUntil, publicUrl |
quotation.accepted | The customer accepted a quotation online. | id, number, customerName, acceptedName, acceptedAt, total, currency |
quotation.declined | The customer declined a quotation online. | id, number, customerName, declineReason, declinedAt |
Invoices
invoice.created | An invoice was created (manually, from a quotation, an order, the API or a recurring schedule). | id, number, status, customerName, total, currency, dueDate, recurringId |
invoice.sent | An invoice was sent to the customer. | id, number, customerName, customerEmail, total, paidAmount, currency, dueDate, publicUrl |
invoice.paid | An invoice became fully paid. | id, number, customerName, total, currency, paidAt |
recurring.generated | A recurring schedule generated a new invoice. | scheduleId, scheduleName, invoiceId, number, total, currency, sent, nextRunAt |
Payments
payment.received | A payment was recorded against an invoice (manual, gateway or wallet claim). | paymentId, invoiceId, invoiceNumber, amount, currency, method, reference, status |
Orders
order.placed | A shop order was placed at checkout. | id, number, customerName, customerEmail, total, currency, paymentMethod, items |
order.status_changed | A shop order moved to a new status (confirmed, shipped, delivered …). | id, number, status, paymentStatus |
Customers
customer.created | A customer account was created (registration, checkout, admin or API). | id, name, email, phone, companyName, countryCode |
Purchasing
purchase_order.sent | A purchase order was sent to the supplier. | id, number, supplierName, total, currency, expectedAt |
purchase_order.received | Goods were received against a purchase order (partial or complete); one goods received note (GRN) per receiving. | id, number, supplierName, status, receivedLines, expenseId, stockUpdates, goodsReceiptId, goodsReceiptNumber |
Deliveries
delivery.created | A delivery note (slip + packing list) was created for an order. | id, number, orderId, orderNumber, customerName, lines, units, packages |
delivery.packed | A delivery note was marked packed (ready for the driver / courier). | id, number, orderId, customerName, packages |
delivery.cancelled | A delivery note was canceled. | id, number, orderId, customerName |
delivery.dispatched | A delivery note was marked dispatched (handed to the courier). | id, number, orderId, orderNumber, customerName, courier, trackingNo, packages, dispatchedAt |
delivery.delivered | A delivery note was marked delivered; orderDelivered is true when it completed the order. | id, number, orderId, orderNumber, customerName, receivedBy, deliveredAt, orderDelivered |
Cheques
cheque.recorded | A cheque was added to the register (received from a customer or issued to a supplier). | id, direction, chequeNo, bank, partyName, amount, currency, chequeDate, invoiceId, supplierId |
cheque.deposited | A cheque was marked deposited. | id, direction, chequeNo, bank, partyName, amount, currency, chequeDate, status |
cheque.cleared | A cheque cleared; for a received cheque linked to an invoice the payment was recorded (paymentId). | id, direction, chequeNo, bank, partyName, amount, currency, chequeDate, status, invoiceId, paymentId |
cheque.bounced | A deposited cheque was returned unpaid. | id, direction, chequeNo, bank, partyName, amount, currency, chequeDate, status, note |
cheque.cancelled | A cheque was canceled in the register. | id, direction, chequeNo, bank, partyName, amount, currency, chequeDate, status, note |
HR
employee.created | An employee record was created (no pay figures). | id, number, name, jobTitle, department, status, startDate |
employee.status_changed | An employee's status changed (active, probation, on leave, resigned, terminated). | id, number, name, status, previousStatus, endDate, via |
hr_letter.issued | An HR letter was issued (offer, appointment, salary certificate, experience, NOC, warning, termination …); the letter body is not included. | id, number, kind, subject, employeeId, employeeNumber, employeeName, date |
Appointments
appointment.booked | An appointment was booked (by staff or online); source is "admin" or "web". | id, number, status, serviceId, serviceName, employeeId, customerId, customerName, customerPhone, customerEmail, startAt, endAt, price, currency, source |
appointment.confirmed | Staff confirmed an appointment with the customer. | id, number, status, serviceName, employeeId, customerId, customerName, startAt, endAt |
appointment.checked_in | The customer arrived and was checked in. | id, number, status, serviceName, employeeId, customerId, customerName, startAt, endAt |
appointment.cancelled | An appointment was canceled by staff or by the customer online (via). | id, number, status, serviceName, customerName, startAt, cancelReason, via |
appointment.completed | An appointment was marked completed. | id, number, status, serviceName, employeeId, customerId, customerName, startAt, price, currency |
appointment.no_show | The customer did not come (marked no-show). | id, number, status, serviceName, customerId, customerName, customerPhone, startAt |
stay.reserved | A room reservation was made (front desk or import). | id, number, guestName, arrival, departure, roomTypeId, roomId |
stay.checked_in | A guest checked in to a room. | id, number, guestName, room |
stay.checked_out | A guest checked out; the folio's tax invoice was issued (invoiceId). | id, number, guestName, nights, invoiceId |
stay.cancelled | A reservation was canceled (invoiceId when a cancellation fee was kept). | id, number, guestName, invoiceId |
stay.no_show | A reserved guest did not arrive (invoiceId when a no-show fee was kept). | id, number, guestName, invoiceId |
Point of sale
pos.sale_completed | A sale was completed at the till (payments, gift cards spent, loyalty points earned). | id, number, sessionId, register, customerId, customerName, subtotal, discountTotal, taxTotal, total, currency, payments, lines, pointsEarned |
pos.sale_refunded | A till sale was (partly) refunded; giftCardCredits lists money put back on gift cards, pointsReversed the loyalty points taken back. | id, number, refundOfId, refundOfNumber, customerId, total, currency, method, payments, giftCardCredits, pointsReversed, reason |
pos.session_closed | A till session was closed with its Z report figures. | id, number, register, openedAt, closedAt, openingCash, expectedCash, countedCash, difference, salesCount, refundCount, net, byMethod |
Inventory
stock.low | A product fell to or below its reorder point in a location (once per crossing; the hourly check re-arms when it is restocked). | productId, name, sku, warehouseId, warehouse, quantity, min, shortfall |
stock.expiring | A batch with stock expires within 30 days (once per batch and expiry date). | productId, name, sku, warehouseId, warehouse, batchNo, expiresAt, days, quantity |
Payroll
leave.requested | A leave request was recorded. | id, employeeId, employeeNumber, employeeName, type, startDate, endDate, days, status, reason |
leave.decided | A leave request was approved, rejected or canceled. | id, employeeId, employeeNumber, employeeName, type, startDate, endDate, days, status, previousStatus, decidedAt |
payroll.paid | A payroll run was marked paid (totals only — never individual salaries). | id, number, period, employees, totalGross, totalNet, currency, paidAt, journalEntryId |
Memberships
membership.created | A member was enrolled on a plan. | id, number, planId, planName, customerId, customerName, customerPhone, customerEmail, startDate, endDate, status, autoRenew, invoiceNumber |
membership.expiring | An active membership ends within 7 days (once per end date; auto-renewing ones included with autoRenew true). | id, number, planName, customerId, customerName, customerPhone, customerEmail, endDate, daysLeft, autoRenew |
membership.expired | An active membership passed its end date without renewal and became EXPIRED. | id, number, planName, customerId, customerName, endDate |
giftcard.issued | A gift card was issued. | id, code, initialValue, balance, currency, expiresAt, purchaserName, recipientName, recipientEmail |
giftcard.redeemed | Money was spent from a gift card (at the till or by staff). | id, code, amount, balance, currency, status, refType, refId |
Affiliates
affiliate.created | An affiliate joined the referral program (application from the customer portal or created by staff); status is PENDING while it waits for approval. | id, code, name, status |
affiliate.status_changed | An affiliate was approved, suspended, rejected or re-activated. | id, code, from, to |
affiliate.conversion | A referred shop order or accepted quotation was attributed to an affiliate (kind, reference); the commission starts as pending. Amounts are minor units of the net value. | id, affiliateId, code, kind, reference, amount, commission, currency |
affiliate.payout_paid | An affiliate payout was marked paid (minor units). | id, number, affiliateId, amount, currency, method, reference |
Pipeline
deal.created | A deal was created in the sales pipeline. | id, title, stage, status, value, currency, probability, expectedClose, ownerId, customerId, contactName, source |
deal.stage_changed | An open deal moved to another stage (board drag and drop or the deal form). | id, title, from, to, value, currency, probability |
deal.won | A deal was won (by staff or because its linked quotation was accepted). | id, title, value, currency, customerId, contactName, quotationId, wonAt, via |
deal.lost | A deal was marked lost with a reason. | id, title, value, currency, lostReason, lostAt |
Support
ticket.created | A support ticket was opened (website form, customer portal, inbound email, staff for a phone call / walk-in, or converted from a lead). Spam is never sent. | id, number, subject, status, priority, channel, category, customerId, name, email, assigneeId, firstResponseDueAt, resolutionDueAt, createdAt |
ticket.updated | A ticket changed: status, assignee, priority / category (new SLA targets), tags, links, merge, SLA breach or customer rating (change / from / to say what). | id, number, subject, status, priority, channel, category, customerId, assigneeId, change, from, to, changes, rating |
ticket.replied | A public message was added: by staff (first: true for the first response) or by the customer (reopened: true when it reopened the ticket). Internal notes are never sent. | id, number, subject, status, priority, customerId, assigneeId, by, first, reopened |
ticket.resolved | Staff marked a ticket resolved (the customer is asked for a rating when the survey is on). | id, number, subject, status, priority, customerId, assigneeId, from, to |
Field service
job.created | A field job (work order) was created: by staff, from a lead or quotation, a contract visit, the customer portal or a booking (source). | id, number, title, status, kind, industry, source, customerId, customerName, customerPhone, customerEmail, technicianId, scheduledStart, contractId, priority |
job.scheduled | A field job got a technician and a time on the dispatch board, or was moved to another time (rescheduled true). | id, number, title, status, customerId, customerName, customerPhone, customerEmail, technicianId, scheduledStart, scheduledEnd, rescheduled |
job.completed | A field job was marked completed (checklist, signature and photos as the settings require). | id, number, title, customerId, customerName, customerPhone, customerEmail, technicianId, contractId, completedAt, invoiceId |
job.invoiced | The draft invoice of a completed field job was created; the job is now invoiced. | id, number, title, customerId, customerName, invoiceId, invoiceNumber, total |
contract.visit_due | A service-contract visit came within the contract's lead time and its job was created (technicianId null = nobody assigned yet). | id, number, contractId, contractNumber, contractName, customerId, customerName, dueOn, technicianId, scheduledStart |
Property
lease.expiring | An active lease ends within 60 days (once per end date; a renewal moves the end date and re-arms it). | id, number, customerId, customerName, customerPhone, customerEmail, endAt, daysLeft, rentAmount, renewalStatus |
lease.renewed | A lease was renewed for more months (new end date; the rent schedule and payment plan run on). | id, number, customerId, customerName, previousEndAt, endAt, months |
rent.overdue | A rent invoice of a lease is unpaid after its due date (once per invoice). | id, number, contractId, contractNumber, customerId, customerName, customerPhone, customerEmail, balance, currency, dueDate, days |
maintenance.reported | A maintenance request was logged on a unit or rental item, by staff or by the tenant in the portal (via). | id, number, contractId, itemId, title, priority, via |
Contracting
progress_claim.submitted | A payment application (progress claim or retention release) was submitted to the client. | id, number, projectId, kind, amountDue, submittedAt |
progress_claim.certified | The client's engineer certified a payment application; its amounts are frozen and it can be invoiced. | id, number, projectId, kind, amountDue, certifiedBy, certificateRef, certifiedAt |
variation.approved | A variation order was approved: online by the client (signature) or recorded by staff (channel). | id, number, projectId, title, amount, currency, channel, approvedName, approvedAt |
Workshop
garage.job_ready | A workshop job card was marked ready: the car can be collected. | id, number, customerId, customerName, customerPhone, customerEmail, vehicle, plate, readyAt, promisedAt |
Laboratory
lab.result_ready | Every result of a lab order is validated: the final report is ready (ids and numbers only, never values). | id, number, reportNumber, referrerId, priority, finalAt |
lab.result_critical | A result outside the critical limits was entered: it must be phoned through (the test code and flag only, never the value). | id, orderId, orderNumber, test, flag, enteredAt |
Clinical
session.signed | A clinical session note was signed and locked (no client name and no note text). | id, template, clientId, appointmentId, serviceDate, authorId, cosignRequired, signedAt |
School
school.fee_due | A school fee instalment is coming due and the payer was reminded (once per instalment). | id, studentId, planId, label, dueAt, amount, balance, invoiceId, customerId, payerName, email, phone |
school.fee_overdue | A school fee instalment passed its due date unpaid. | id, studentId, planId, label, dueAt, amount, balance, invoiceId, customerId, payerName, email, phone |
attendance.absent | A student was marked absent at the roll call (once per day and slot; a later change to present or excused closes it). | id, studentId, studentNumber, sectionId, section, date, slot |
Insurance claims
insurance_claim.denied | A remittance denied a health-insurance claim in full or in part (amounts and payer codes only). | id, number, payerId, status, paid, denied, denialCodes, remittanceNumber |
insurance_claim.paid | A health-insurance claim was paid in full by the insurer's remittance. | id, number, payerId, status, paid, remittanceNumber |
Logistics
shipment.delivered | A parcel was delivered (or partly delivered), or a freight job reached delivered (kind: parcel | freight). | id, kind, number, status, merchantId, customerId, customerName, deliveredAt, partial |
shipment.exception | A delivery attempt failed (reason, attempts so far, next attempt day; rto true when the parcel now goes back to the merchant). | id, kind, number, status, merchantId, reason, attempts, nextAttemptDay, rto |
Insurance agency
policy.renewal_due | An insurance policy reached its renewal window (the producer's follow-up task was made; once per policy term). | id, number, policyNumber, customerId, customerName, email, phone, insurerName, endDate, daysLeft, producerId |
System
webhook.test | Sent by the “Send test event” button on the Integrations page. | endpointId, message, at |
التالي: خادم MCP
اربط عميل ذكاء اصطناعي بمساحة عمل عبر Model Context Protocol بصلاحيات الشخص نفسه.