Product

MARREK API and Webhooks: Connect the AI Consultant to Your Own Product

MARREK now has a public REST API and signed webhooks. Learn how to create an API key, subscribe to events, choose what each integration may access, and track every delivery in the Delivery log.

MARREK Team7 min read

MARREK answers your customers in Instagram, Telegram and on your website. Until now, everything it collected — dialogs, leads, the catalogue, statistics — lived in the MARREK dashboard. Now your own software can work with the same data: MARREK has a public REST API and signed webhooks. Your CRM, ERP, BI dashboard or in-house tool can read dialogs and reply to customers, sync leads, manage products and the knowledge base — and hear about every new message the moment it arrives.

What you can build with the API and webhooks

  • Sync leads into any CRM — even one MARREK has no ready-made integration for.
  • Reply from your own system. Managers work in a familiar interface; replies go out to the customer’s Instagram or Telegram through MARREK.
  • Keep the catalogue in step with your shop or warehouse: create, update and remove products automatically, so the AI always quotes current prices.
  • Feed the knowledge base from your wiki or help center.
  • Pull analytics into your BI tool alongside the rest of your sales data.
  • React instantly — a webhook on a new lead can notify a salesperson, open a task or start a follow-up.

How to create an API key

An API key lets your server call MARREK on your behalf. Create a separate key for each integration — then you can limit it precisely and revoke it without touching the others.

  1. In the MARREK dashboard open Developers → API keys and click Create key.
  2. Give it a clear name, for example “CRM sync”.
  3. Choose the access for each area: no access, read, or read and write. The Read only and Full access presets fill everything in one click.
  4. Optionally limit the key to selected projects — say, one shop out of several — and set an expiry date.
  5. Click Create and copy the key (it starts with mk_live_). It is shown only once.

Your server then sends the key in the Authorization: Bearer mk_live_… header. The dashboard shows when each key was last used, and a key can be revoked at any moment — it stops working immediately.

What access you can grant

Every key gets exactly the rights you give it, area by area. “Read and write” always includes “read”. A request outside the key’s rights is refused, so a mistake in one integration cannot touch data it was never meant to see.

API access areas and what each level allows
AreaReadRead and write
DialogsList dialogs and read messagesSend replies and attachments, mark as read, switch the AI on or off, change the lead status
LeadsRead and export leadsEdit and delete leads
Products & categoriesRead the catalogueCreate, edit and delete products and categories
Knowledge baseRead documentsAdd and manage documents
AI settingsRead the prompt and behaviourChange the prompt and behaviour
AnalyticsRead statistics—

Give each integration the least it needs. A key that only feeds your BI tool needs Analytics: read and nothing else.

How to subscribe to webhooks

The API lets you ask MARREK for data; webhooks let MARREK tell you about it. Instead of polling every few seconds, your server receives an HTTPS request the moment something happens.

  1. Open Developers → Webhooks and click Add endpoint.
  2. Enter the URL of your server — a public https:// address.
  3. Choose the events: all of them (including ones we add later) or only the ones you need.
  4. Choose the projects the endpoint should hear from.
  5. Click Create and copy the signing secret. It is shown once and lets you verify that every request really comes from MARREK.
  6. Click Send test to check that your endpoint answers before real events arrive.
Events you can subscribe to
EventWhen it is sent
message.receivedA customer wrote a message (Telegram, Instagram, web widget)
message.sentA reply was created — by the AI, a manager or the API
message.updatedA message’s delivery status changed or an attachment is ready
thread.createdA new dialog started
thread.updatedA dialog’s status, AI switch, assignee or lead status changed
lead.createdThe first contact details of a customer were captured
lead.updatedA lead was updated by the AI or edited by a person
lead.deletedA lead was deleted

Every request is signed with HMAC-SHA256 in the X-Marrek-Signature header, and the event body has the same shape as the REST API response — you learn one format, not two. Message events also include the dialog, so you know who wrote without a second call.

The Delivery log: see every webhook that was sent

The hardest part of webhooks is usually figuring out what went wrong: did the event fire, did it reach the server, what did the server answer? In MARREK the answer is one tab away — Developers → Delivery log.

  • Every event sent to your endpoints — with its type, endpoint, creation time, number of attempts and the HTTP code your server returned.
  • Filters by endpoint, status and event, so you can find the one delivery you need.
  • Each attempt in detail — HTTP status, duration and your server’s response.
  • The exact payload that was sent — handy when you debug your handler.
  • Send again for a single delivery, or Replay missed on an endpoint to resend everything it did not receive.
Delivery statuses in the Delivery log
StatusWhat it means
Queued / SendingThe event is waiting to be sent or is being sent right now
DeliveredYour server answered with a 2xx status
Will retryA temporary error (timeout, 429, 5xx) — MARREK will try again automatically
RejectedYour server answered with a 4xx error, which is treated as a configuration problem and not retried
Gave upAll retry attempts have been used
SkippedThe event was not sent — for example, the endpoint was switched off

Temporary failures are retried with growing delays — up to 10 attempts over 24 hours. If an endpoint keeps failing, MARREK pauses it so as not to overload your server, and you see it right in the dashboard. Events are kept, so once the server is fixed you can replay everything that was missed.

Documentation for developers

Everything a developer needs is public, no account required:

  • The integration guide — quick start, authentication, projects, access, errors and limits, webhook signature verification with ready-made examples in PHP, Node.js and Python.
  • The API reference — every endpoint with parameters, schemas and a “Try it” console.
  • An OpenAPI document that imports into Postman and works with code generators.

Frequently asked questions

Does sending a message through the API use my AI message allowance?

No. A message sent through the API counts as a manager’s message. AI replies to customers count as usual.

Can I limit a key to one project?

Yes. When you create a key or a webhook endpoint, choose “Only selected projects” and tick the ones it may reach.

What happens if I switch to a plan without the API?

Your keys and endpoints are kept, but requests are refused and webhooks are not sent. Upgrade to bring them back, and replay what was skipped from the Delivery log.

Is there an official SDK for the API?

Not yet. The OpenAPI document works with generators such as openapi-generator, so you can create a client for your language in minutes.

The takeaway

The API and webhooks turn MARREK from a separate dashboard into part of your own system: the AI consultant talks to customers, and your software receives the dialogs and leads in real time, with exactly the access you allowed. Start with the integration guide, or see which ready-made connections exist in the CRM integration overview.

Put an AI consultant to work in your business

Connect Telegram, Instagram or your website, upload your catalogue, and let MARREK answer customers 24/7. Free 7-day trial.