Agent webhooks
Needlr can post each verdict to your agent's server the moment it's ready, signed so your server knows it came from Needlr.
Your agent asked Needlr to measure a release. The verdict may land days later, when the agent isn't running. A webhook pushes it to your server the moment it's ready.
A webhook lets Needlr tell your agent's server the moment one of its impact checks has a verdict. Your agent doesn't have to keep asking.
Think of a doorbell
You're waiting for a parcel. You could walk to the mailbox every hour to look. Or you could have a doorbell: the courier rings once, when the parcel arrives.
Without a webhook, your agent walks to the mailbox: it asks Needlr for its verdicts when it comes back. With a webhook, Needlr rings the bell.
When to use it
- Your agent runs on a server, in a CI pipeline, or as a bot that can receive a web request.
- You want the agent to act on a verdict right away, not at its next session. Split tests often take a week or more.
- Your agent only runs in an editor on a laptop. It can't receive requests. It reads its verdicts when a session starts.
- You want results for yourself. Use emails and alerts.
Set it up
- 1Open Agents in the menu on the left. Owners and Editors can do this.
- 2On the agent's card, next to Verdicts sent to:, press Add a webhook.
- 3Paste the address on your server where Needlr should post, like https://your-server.example/needlr. Press Save.
- 4Enter the code from your authenticator app. Sending your results to an address outside Needlr always needs one.
- 5A green box shows the secret. Press Copy secret and store it on your server. It's shown only once.
The card now shows your server's name next to Verdicts sent to:. Verdicts from the last 30 days that were never posted for this agent go out too.
Which addresses work
- It starts with https://.
- It uses a real domain name, like api.acme.com. Not an IP address, and not localhost.
- No other port than the normal one, and no user name or password inside it.
- Needlr doesn't follow redirects. A redirect counts as a failed delivery.
When Needlr posts
Only for impact checks this agent asked for. Two moments:
- A verdict is ready. Any result: improved, got worse, no clear effect, or an adoption result. A split test that stopped itself because it hurt (Stopped · it hurt) is sent this way too. The event is called check.verdict_ready.
- A data problem. A running impact check went on hold. The event is called check.data_problem. It's sent once per impact check.
What's in a post
A JSON body with four parts:
- event: check.verdict_ready or check.data_problem.
- sentAt: when it was sent.
- agent: the agent's id and name.
- check: the impact check, exactly as your agent would read it from Needlr: its state, the effect and its range, the recommended next step, a one-line summary, and a link to its check page.
Needlr-Event repeats the event. Needlr-Delivery is an id that stays the same when a post is retried, so your server can skip one it already handled.
Check that it came from Needlr
Anyone can send a request to your server. The signature proves a post came from Needlr. Your developer checks it like this:
- 1Read the Needlr-Signature header. It looks like t=1760528400,v1=8f3a… . The t part is when it was sent, in seconds. The v1 part is the signature.
- 2Put together t, a dot, and the body exactly as it arrived: 1760528400.{"event":…}.
- 3Compute HMAC-SHA256 of that text with your secret, written in hex.
- 4If it equals v1, the post is from Needlr. If not, drop it. You can also drop posts whose t is too old.
Answer quickly
Answer with any 2xx status within 10 seconds. That counts as delivered. Do any slow work after you answer.
If your server doesn't answer
Needlr tries again 6 times: after 1 minute, then 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. That's about 20 hours in all. After the last try, it gives up on that post.
The card shows how many deliveries failed in a row, and the last error, like unreachable or http_500. One delivery that works sets the count back to zero.
Good to know
- One webhook per agent.
- A paused agent gets no posts. Verdicts that arrive while it's paused aren't sent later. The agent can still read them when it's back.
- Setting a webhook needs a code; removing one doesn't. Both show on the Activity page.
- Your agent can always ask. A webhook is extra. Without one, the agent reads its verdicts the next time it asks.
Common mistakes
- Not checking the signature. Then anyone who finds the address can send your agent fake verdicts.
- Losing the secret. It's shown once. Remove the webhook and add it again to get a new one.
- Doing slow work before answering. After 10 seconds, Needlr counts it as failed and tries again later.
What the video says
Your agent asked Needlr to measure a release. The verdict may land days later, when the agent isn't running. A webhook pushes it to your server the moment it's ready.
On the agent's card, press Add a webhook. Paste the address on your server where Needlr should post, press Save, and confirm with a code from your phone.
Needlr then shows a secret once. Copy it. Every post carries a signature made with that secret, so your server can prove it came from Needlr and drop anything else.
Two moments trigger a post: a verdict, including a split test that stopped because it hurt, and a data problem. The body is what your agent would read: verdict, effect, next step.
If your server is down or returns an error, Needlr retries six times over about 20 hours: after one minute, five, thirty, then two, six and twelve hours.
After 50 failed deliveries in a row, the webhook switches off, and the card says so. Fix your server, then remove it and add it again. Verdicts reach your agent either way.