Connect a source

A source is one team’s errors or one team’s deploys. It is what tells an incoming webhook which organisation it belongs to, and it is created from the Sources screen — nothing here needs database access, and nobody at the other end needs an account with us. Connecting one is a guided sequence, not a form. Press Connect a Sentry source or Connect a GitHub repository on the Sources screen and the dialog walks you through it one step at a time, handing over each value at the step that needs it.

​

The one thing to know before you start

The secret travels in opposite directions for the two vendors, and getting it backwards produces a source that refuses every delivery and looks like a mistake the other team made. A Sentry Internal Integration mints its own Client Secret and signs every delivery with it. There is no field anywhere in Sentry to paste a secret of ours into. So the two sequences are genuinely different shapes: GitHub is one sitting and nothing comes back; Sentry is two sittings, days apart, and the last step is you pasting in what they replied with.

​

What a finding from this source will say

Findings say an error is new, and which release it followed. They never say how often it is firing. That is the whole shape of what comes back, it is the same for every source on either Sentry route, and there is nothing at either end that switches the other half on. It is worth knowing before you send anything, because it is the one thing a team lending us their errors expects and does not get. How an investigation opens carries the reasoning; the short version is that the route we ask for is throttled per issue, so a rate counted from it is wrong in a direction nobody controls — and where a rate can be counted exactly, it is a number their error tracker already shows them, better than we could from outside. You do not have to remember to say it. The sequence puts it on the step before you send anything, and the message you copy says it to them in their own words — so a team reads it while they are deciding whether to configure a webhook, rather than after their first quiet fortnight.

​

Sentry — four steps, two sittings

The address is minted at step 1, before any secret exists, so that the Webhook URL field Sentry asks for at the moment the integration is created has a real value to receive. The source exists from that point on and holds no secret until they reply: it refuses every delivery, and the Sources screen shows it as Waiting for their secret with how long it has been waiting.

​

What the other team is asked to do

Three things, in this order, and the message you send carries all of them:

1. Settings → Developer Settings → Custom Integrations → Create New Integration → Internal. The Webhook URL field takes the address from step 2. Alert Rule Action is turned on. Every other field is left exactly as it comes — none of them change what reaches us.
2. Save it. Sentry then shows a Client Secret. That is the only thing we need back, and nothing arrives until we have it.
3. Alerts → Create Alert → Issues. Any conditions that suit them, with the action set to Send a notification via that integration. This is what actually sends us events.

If Sentry ever regenerates the Client Secret, use Replace the Client Secret on the source and enter the new value. Nothing on their side has to change, and the source keeps everything it has stored — which matters, because a source that has stored signals cannot be deleted and remade.

​

Which delivery to configure

There are two routes into this product. Ask for the issue alert rule. Ask for the alert rule. It sends the event with its release on it — the field every finding needs in order to name the deploy it followed — and it is available on Sentry accounts where the error-event subscription is not. They create it under Alerts → Create Alert → Issues, with the action set to Send a notification via the integration. The error event subscription reaches the same place and we read it just the same. It is not offered on every Sentry account: where it is not, Sentry refuses the subscription outright with “Your organization does not have access to the error subscription resource.” Asking for it first is what sent the first real integration into a gate it did not need to pass. Which route a source ended up on is shown on its own row, read off the deliveries that actually arrived — you never have to ask them what they are paying for, and we do not record it.

​

The percentage on the source row

Once errors are arriving, the source row says how many of the errors stored this week carry no usable release. It is read off the release the sending project put on the event, not off anything of ours. An error with no release still produces a finding — a weaker one, which cannot say which deploy it followed — so the percentage is a quality figure and never an outage. Zero is the answer for a source on the alert-rule route sending events that carry a release. A high percentage has one ordinary cause and one remedy. The issue route carries no release at all, so a source configured that way reports 100% and the fix is to ask for the issue alert rule described above. If a source is on the alert rule and the figure is still high, their events are being sent without a release set, which is a setting in their own SDK rather than anything in the integration.

​

GitHub — three steps, one sitting

We mint the secret here, it goes out with the address in the same message, and nothing comes back. There is no third step and no waiting. Everything else GitHub sends is received, counted and ignored. That is not a failure — a repository webhook receives every event the repository has.

​

Going back through the step that shows the secret

Inside one sitting the sequence is generous; at the edge of it, it stops.

• Back, while the dialog is open, re-shows the GitHub secret. The value is already on the page, so refusing to draw it again would protect nothing and would strand you if your paste went into the wrong window. Every control that goes back to it says so in its own label before you press it.
• Closing the dialog ends the only copy. Reopening the source lands on a screen that says so and names replacement as the only route, with what replacement costs attached.
• Every way out before you have copied — the close button, Esc, a click outside — asks the same single question. It is the only confirmation in either sequence, and it guards the only irreversible thing in them.

​

When a finding can first arrive

Each source is deliberately quiet for its first fortnight, and the exact date is stated on the source’s own row as well as in the message you send. The sequence states it once, on its last step, and tells you the row is where it lives from then on. The first days of a source’s traffic are what say what normal looks like for it, and anything raised before that would be raised against nothing. The date is given out because a suppression window the other team cannot see is indistinguishable from a broken integration — they would spend two weeks re-checking a webhook that works. It is the date after which silence starts being worth a question, and it is the only date on the screen that means that. The quiet is enforced, not merely promised: nothing raised before that date reaches you. It is also not the product asleep — investigations still open and decisions are still written down, and what was held is released to you on the day the fortnight ends, marked as held. Your first fortnight is the whole of it.

​

Reading the health of a source

The screen separates questions that look identical if you only count signals.

​

Waiting for a secret is not the same silence as being quiet

A source waiting for its Client Secret and a source that is connected and deliberately quiet are both silent, and only one of them can ever work. The screen never lets them read the same. The waiting one is amber rather than red — a source that has never been up is not down — and three things separate it from every other row at a glance: the badge names what is missing, the row carries how many days it has waited, and it is the only silent row with a button on it. A waiting source cannot sit there unnoticed. It carries, from the day it is prepared, the date after which the wait stops being a slow reply. Past that date the sentence on the row changes and the source is listed at the top of the Sources screen among the connections that have stalled. Nothing about a stalled connection is sent to the other team automatically. Chasing somebody for a reply is a message a person writes, reads and sends. The row says so, in those words, so that its silence about contacting anyone is not read as a promise nobody made.

​

Quiet is not broken, and on Sentry we cannot tell the difference

A Sentry source that has sent nothing for days may be perfectly healthy. On the alert-rule route the deliveries are throttled per issue and are sent only when an issue actually fires, so how quiet a healthy source is depends on the rule that was written and on whether anything is going wrong. A calm week legitimately produces nothing at all. So a quiet Sentry row is shown as Quiet rather than as a failure, and it says on the row what it cannot tell you:

Two things look exactly like this from here and we cannot tell them apart: an alert rule that is still in place on a product with nothing going wrong, and an integration that no longer exists at Sentry.

That sentence is on every quiet Sentry row, not only on the ones that look suspicious, because there is nothing about a row that makes one reading likelier than the other. If you need to know which it is, ask them — the product will not ask for you. Nothing on this screen sends anything to the team who configured the source. Telling somebody their integration looks dead is a message a person writes and sends. A GitHub source is read differently, and deliberately: a repository webhook fires on every push, deployment and deployment status the repository has, so a repository that has gone silent for longer than its figure has either stopped or been disconnected. The age of the last stored signal is shown per kind, always — including when the source looks healthy. A source storing errors every minute while it has stopped storing deploys is half broken, and a single number averages that away. A healthy badge over a three-day-old age is what a silently paused integration looks like, which is the thing worth watching for. The route each Sentry source is on is shown on its row, read off the delivery types that have actually arrived. That is how you tell an alert rule — throttled, quiet by design — from an error-event subscription, where a gap in the deliveries is a gap in the errors themselves. Until something arrives, the route is not known, and the row says so rather than guessing. A row stops describing itself as storing after 24 hours of silence for errors and 72 for deploys. Both figures are printed on the screen and neither has been measured yet — they are a starting position, not a promise about how quickly anything is noticed. On a Sentry source the figure decides only when the row stops saying Storing; it never decides that anything is broken.

​

What we keep

We keep every delivery whole, exactly as it was sent — not a summary of it — alongside the few fields we read out of it and a running count of which delivery types arrive. That is more than it sounds like, and the message you send says so in the same words. A Sentry error delivery carries stack traces, the request URL with its headers and its cookies, and any user email address or IP address attached to the event. A GitHub push carries the name and email address of every commit author in it. We do not drop fields on the way in, so anything the other team would rather we did not hold has to be filtered before the delivery leaves them. We keep the delivery rather than a summary because a figure we publish this month has to be recomputable against the original when it turns out to be wrong. The alternative is correcting a number by editing the evidence underneath it. Everything held for a source is deleted within 7 days of a written request, and in any case by the date stated in the message.

​

Removing a source

A source that has stored signals cannot be deleted. The attempt is refused and the signals survive it. Signals are evidence, and deleting a source as a tidy-up would take its evidence with it without anybody intending that. Removing the signals is a separate, deliberate operation: it names one source, it records who ran it and why, and it leaves a record saying so. Ask us for it in writing — we act on a request within 7 days. A source that has never stored anything — including one still waiting for its Client Secret — is removed from the screen directly. There is nothing to lose.