Declaring events

You can name an event in Settings → Data → Events before your application has ever sent one. The name becomes available in workflows and segments straight away.

Why you would

A workflow's trigger is an event name, matched when the event arrives. That has always meant you could build a workflow for an event that does not exist yet — but the suggestion list only showed events that had already been received, so the name was invisible until something fired it. People worked around that by sending a throwaway event just to make the name appear.

Declaring removes the workaround. Build the automation this morning, ship the code that sends the event this afternoon.

What it does, and what it does not

Declaring an event makes its name visible and documented. That is all.

• It appears in the workflow and segment pickers immediately.
• It carries a display name and a description, like any other event.
• The events list shows it as not yet received until the first one arrives — which is a useful thing to see on its own. An event you declared three weeks ago that has still never arrived is an integration that was never finished.

Nothing is rejected. Events you never declared are received exactly as before. Declaring is not a registry that events have to be in; it does not validate anything, and it changes nothing about how workflows or segments match.

Sending it

Use the same project’s public key and the exact event name. This example explicitly leaves the contact unsubscribed; do not overwrite an existing consent choice when sending routine events:

curl -X POST https://api.bitelio.com/v1/track \
  -H "Authorization: Bearer pk_YOUR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user.signup",
    "email": "customer@example.com",
    "subscribed": false,
    "data": { "plan": "pro" }
  }'

The email is required. It is how the event is attributed to a contact, and it is the first reason a first attempt usually fails.

Choose the right authentication

/v1/track accepts only the public key (pk_*), not a secret key. Send business events from your backend after validating the source, but do not treat the public key as proof of a purchase or of the caller's identity. Anyone holding it can submit events for an email address and start matching workflows.

Keep secret keys on your server for endpoints that require them, such as contact management. Never use an event received through the public endpoint to authorize refunds, rewards or access. For a complete contact-and-purchase integration, see Connect a custom CMS.

Removing a declaration

Deleting the declaration of an event that has already been received does not remove the event. It goes back to being an ordinary event: still listed, still selectable, just without the display name and description you gave it.

Only an event that was declared and never received disappears completely — once the declaration is gone, there is nothing left that knows the name.

Neither deletes any event data. That is a separate action on the same screen.