Webhooks

Inbound webhooks are the universal way into Nybero: every webhook you create gets a unique public URL. Any external system — a website form builder, a quiz tool, an automation platform like Zapier or Make, your own backend — can POST data to that URL. Nybero maps the incoming fields onto a contact (new or existing, matched by phone number) and can start an automation via the Webhook received trigger.

You’ll find them under Integrations → Webhooks. This page is a bit more technical than the rest of the docs — if you just paste the URL into a form tool’s “webhook” field, the built-in test flow does the heavy lifting for you.

How it works

1. You create a webhook — Nybero mints a URL of the form:

   https://app.nybero.com/api/public/hooks/{workspace-id}/{token}

2. An external tool sends an HTTP POST with a JSON body (form-encoded bodies work too — many form plugins and CRMs post that way).

3. Nybero applies your field mapping: each incoming JSON field is written to a contact field. Exactly one field must be mapped as Phone — the phone number is the contact’s identity. If a contact with that number exists, it’s updated; otherwise a new contact is created.

4. Optionally, the contact is marked as opted-in and the Webhook received trigger fires your automations.

Create a webhook

1. Go to Integrations → Webhooks and click + New webhook.
2. Give it a Name and a Description (e.g. “Elementor lead form on the landing page”) so you remember where it comes from.
3. Copy the Webhook URL (POST · JSON) and paste it into the external tool’s webhook settings.

Settings

• Active — only active webhooks process incoming data (an inactive one still accepts a test event while you’re listening for one).
• Treat as opt-in (consent obtained at the source) — tick this only if the source genuinely collects WhatsApp consent (e.g. a checkbox on your form). Incoming contacts are then marked as opted-in and a consent-log entry is written, naming the webhook as the source — see Opt-in management. A contact who has opted out is never opted back in by a webhook.
• Default country for numbers — used to interpret phone numbers without a country code (e.g. 0176 1234567 → +49 176 1234567). Numbers that already start with + are always parsed as-is.
• Signature secret (optional) — see Security below.

Map the incoming fields

The mapping tells Nybero what each JSON field means. The editor guides you through it:

1 · Receive a test event

Click Wait for test event (60 s), then trigger a real submission in your external tool (submit your form once, run the Zap once). The first incoming payload is captured — it is not turned into a contact — and Nybero jumps straight to the mapping with every field detected.

Alternatively click Or paste JSON manually, paste a sample payload, and hit Detect fields.

2 · Mapping

You get a table with one row per detected field — JSON field (the path), Sample value, and Target in CRM:

• Phone (required identity) — exactly one field must be mapped as phone.
• Name, Source, Language — core contact fields.
• Any existing custom field — or + Create new field… to create one on the spot.
• Ignore — drop the field.

Nybero pre-suggests sensible targets (a field called phone or whatsapp becomes Phone, first_name becomes Name, etc.) — review and adjust, then click Save & done.

Nested JSON is flattened to dot paths: {"contact": {"email": "a@b.com"}} appears as contact.email. Items in arrays of objects are addressed by index (items.0.sku).

Test with curl

Once the mapping is saved, send a realistic payload yourself:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Lopez",
    "phone": "+14155550123",
    "email": "maria@example.com",
    "source": "landingpage-june"
  }' \
  "https://app.nybero.com/api/public/hooks/YOUR-WORKSPACE-ID/YOUR-TOKEN"

A successful call answers:

{ "ok": true, "contact_id": "6f9c1e2a-…", "created": true }

created is true for a brand-new contact and false when an existing contact (same phone number) was updated.

If something’s wrong, the response tells you why, e.g.:

{ "ok": false, "rejected": true, "reason": "No phone number in the payload" }

Event log

Both the webhook’s detail page and the editor show Recent events — the last received payloads, each with a status:

Status	Meaning
Created	A new contact was created (with a “View contact →” link)
Updated	An existing contact was updated
Captured (test)	Received while listening for a test event — not processed
Rejected	Not processed — the reason is shown (e.g. missing or invalid phone number)

Connect external tools

Anything that can send a webhook can feed Nybero:

• Website form builders (Elementor, WPForms, Gravity Forms, Typeform, ClickFunnels, …) — look for “webhook” in the form’s actions/notifications settings and paste your Nybero URL. Both JSON and classic form-encoded submissions are accepted.
• Automation platforms (Zapier, Make, n8n, …) — add an HTTP/webhook action pointing at your Nybero URL, and map the fields of the upstream trigger (new order, new booking, new row, …) into the JSON body.
• Your own code — a single POST per lead, as in the curl example above.

Create one webhook per source. That keeps mappings clean and lets your automations react differently per source.

Fire automations

In the automation builder, choose the trigger Webhook received. You can react to Any webhook or pick one specific webhook — so your “webinar landing page” webhook can start a different flow than your “shop orders” webhook.

The automation starts for the contact the payload was mapped to, immediately after processing.

Caution

Whether you can message the new contact right away depends on WhatsApp’s rules: without an open 24-hour window, the first message must be an approved template. And regardless of the channel rules, only message contacts who consented — that’s what Treat as opt-in documents.

Security

• The URL contains a long random token — treat it like a password. If it leaks, delete the webhook and create a new one (new token, new URL).
• For sources you control, set a Signature secret. Requests must then carry the header X-Nybero-Signature: sha256=<HMAC-SHA256 of the raw request body, hex> — anything unsigned or wrongly signed is rejected with 401.
• Inbound traffic is rate-limited (per webhook, and per phone number) to protect your workspace from floods.

Worked example: landing-page form → contact → welcome automation

Your landing page runs on a form builder that can call a webhook on submit. The form asks for name, phone, and email, and has a consent checkbox for WhatsApp updates.

1. Create the webhook — Integrations → Webhooks → + New webhook, name it “Landing page June”, description “Form on /summer-offer”.

2. Settings — tick Treat as opt-in (consent obtained at the source) (the form has a consent checkbox) and set Default country for numbers to your audience’s country.

3. Wire the form — paste the Webhook URL into the form builder’s webhook action.

4. Map the fields — click Wait for test event (60 s) and submit the form once. Nybero captures:

   { "name": "Jonas Weber", "phone": "0176 1234567", "email": "jonas@example.com" }

   Map phone → Phone (required identity), name → Name, email → + Create new field… → “Email”. Click Save & done.

5. Build the automation — new automation, trigger Webhook received → “Landing page June”. First step: Send WhatsApp template with your approved welcome template (“Hi {{1}}, thanks for signing up — reply YES for this week’s offer”). Then a Wait for event step for the reply, and so on.

6. Go live — from now on, every form submission creates (or updates) a contact with a confirmed opt-in and a consent-log entry, the welcome automation fires, and each event shows up under Recent events with a Created/Updated status and a link to the contact.

If a submission ever shows up as Rejected, the reason column tells you what to fix — nearly always a missing or unparseable phone number (check the Default country setting first).