# Declaring events (/guides/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:

```bash
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](/guides/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.