WEBHOOKS AND EVENTS
Start a plan when something happens¶
An incident opens in New Relic, and an agent starts investigating before anyone is paged. A webhook takes events from a sender, and the plans you bound to it start, each with its own record of what it did.
A webhook is one sender of events, such as a New Relic account, with its own address and key. A plan bound to it starts when that sender reports something the plan listens for.
This page is for teams that want agents to start on their own, from the monitoring tools they already use.
For New Relic, EKKA sets up the sender's side from your own Enclave, and the key is made there: nobody ever sees it. Every event is decided once, and each plan it starts is a delivery with its own outcome and its own run.
So an alert can start real work while the key, the decision and the record all stay under your control.
How do I add a webhook?¶
Name it, say who sends, and say which event types it may send.
New Relic. EKKA creates the sender's side on your Enclave. The key is made there and never shown. The webhook starts as configured, not live.
A sender EKKA does not set up. --show-key makes the key here and shows it
once. With --key-file it is written to a new file only you can read, and shown
to nobody:
ekka webhook add docs-example --provider newrelic --type ekka.monitoring.incidentOpened \
--show-key --key-file /tmp/docs-example.key
ekka webhook show <name> prints its address, its state, how old its key is,
and how many events it accepted and refused today and this week.
How does a webhook start a plan?¶
Bind the plan, then make the webhook live.
- Binding pins the plan's latest version, and the answer says which. A newer
version starts only after you bind again.
--unbind <plan>stops it. - Event types change one command at a time with
--allowand--disallow. Allowing a type that a bound plan listens for would start that plan for it too: EKKA names those plans and changes nothing until you add--yes. - New Relic asks which issues to send:
--issues-filter <file>with New Relic's predicates, or--all-issues. There is no silent default.
What did a webhook send, and what did it start?¶
ekka events list # events EKKA accepted, newest first
ekka events show <event> # one event: each plan it started, its outcome, and its run
ekka events cancel <event> # cancel its waiting deliveries
A request a webhook refused is not an event. Refusals are in the audit chain:
ekka audit list --type event.refused.
To try a plan without waiting for a real incident, send one event by hand. It is a real event, and the plans bound to the webhook can start real runs:
How do I change or retire a webhook?¶
| To | Run |
|---|---|
| Stop taking events for a while | ekka webhook pause <name> |
| Take events again, and start what it held | ekka webhook resume <name> |
| Change its key (the old one keeps working for 24 hours) | ekka webhook rotate-key <name> |
| Change its key and stop the old one at once | ekka webhook rotate-key <name> --revoke-old |
| Delete it, and what EKKA set up at its sender | ekka webhook delete <name> |
A rotated key for a webhook EKKA set up goes straight into the sender, and
nobody sees it. Deleting asks you to type the name, or takes
--confirm <name>. Its waiting deliveries are canceled; runs already started
continue.
Can I add my own event types?¶
Yes. ekka events register <name> --contract <file> registers an event type, or
its next version, from a contract file. EKKA puts your organization's prefix in
front of the name. Registering and sending events needs an owner or admin.
Limits¶
- An event type a webhook sends has to be registered and visible to your organization.
- A webhook's key is shown at most once, and only when you ask with
--show-key. - A sent event is a real event: plans bound to the webhook start real runs.
Every ekka webhook and ekka events
command is in the CLI reference.