Skip to main content

How webhooks work

A webhook tells one of your own systems what just happened in Jaah. You give Jaah an endpoint: a public https:// URL, the events to send there, and the projects they may come from. Each time one of those events happens, Jaah sends your URL a signed HTTPS request describing it. Your system can then open a ticket, post to a chat, start a build or update a dashboard, without anyone watching the console.

Terms​

TermMeaning
EndpointOne URL Jaah sends events to, with its name, events, projects and secret.
EventSomething that happened, such as Task done or Pull request merged. The full list is in the event catalog.
DeliveryOne event sent to one endpoint, with every attempt it took.
Signing secretA secret only you and Jaah hold. Each delivery is signed with it, so your system can tell it came from Jaah.

How it relates to the rest of Jaah​

Webhooks carry events out of Jaah. The events are about tasks and the pull requests they open: a task was created, started, is waiting for an answer, finished, failed or was stopped, and a pull request was opened or merged. A delivery carries ids, titles and links, never a task's brief or transcript.

They are not the same as an automation with a Webhook trigger, which works the other way round: another system calls Jaah, and Jaah files a task. Webhooks are also separate from notifications, which tell a person, in the console or on email, Slack or Telegram. A webhook talks to a program.

Only your organization's Owners and Admins see webhooks, and only while your plan includes them. Every change to an endpoint, and every test or redelivery, is recorded in Audit.

An endpoint's life​

A new endpoint starts Enabled and sends only what happens after you save it. Clear Enabled to pause it: events while it is Disabled are never sent later. Jaah shows the signing secret once, when the endpoint is created. Rotate replaces it; for 24 hours each delivery is signed with both the old and the new secret, so your system has time to switch. If the secret leaks, see Replace a webhook signing secret. Deleting an endpoint deletes its delivery log too.

A delivery's life​

A delivery waits as Queued until its first attempt. When your system does not answer in time, or answers with anything but success, the delivery is Retrying and Jaah tries again over the next day. It ends Delivered, or Failed once its attempts run out; a Send test delivery is not retried, so it fails after one attempt. Redeliver, on any row, sends it again at once with a fresh round of attempts. The Deliveries tab keeps 30 days of them. The schedule and the timeout are in Answer and retries.