Skip to content

Alerts are not reaching an overseer

AIR raised an alert about someone your team has a duty of care to, and the person who needed to know did not hear about it.

The alert itself is not lost

An alert is always recorded and always sent to your own people first. What this page is about is the second route — out to an overseer who is not in your organisation, usually a parent or guardian. If that route is broken, the alert still exists and your managers still have it.

An alert reaches an overseer through four things, in order. Any one of them stops it, so work down the list — the first thing you fix may not be the last.

1. Does the participant have an overseer?

Open the team's address book and find the person the alert was about.

An overseer is someone linked to that participant with oversight turned on. Without a link, there is nobody for AIR to send to, and that is not an error — plenty of teams have no external overseers at all, and your own managers are the people with duty of care.

If there is no link and there should be: add the overseer to the address book and link them to the participant with oversight enabled.

2. Does the team have a front door that can deliver?

Overseer alerts leave through the team's SDK door. Go to the team, find the door, and check it has:

  • a webhook URL — where we send to
  • a signing secret — how the other end knows it is really us
  • status live

If there is no SDK door, alerts have nowhere to go. Open one, or ask the person who runs the application on the other side for the URL to send to.

3. Is the door actually delivering?

This is the one that catches people out, because a door can read live and still be delivering nothing. Live means it is configured. The deliveries line tells you whether anything is getting through.

What it says What it means What to do
arriving — last one … Working. Nothing.
nothing sent through here yet Configured, never used. Nothing yet — it will report once something is sent.
the last one didn't get through; still trying A temporary problem. Wait. AIR retries automatically.
the partner is rejecting us — the signing secret has probably drifted The two sides no longer agree on the secret. Re-sync the secret.
nothing is answering at this address The URL is wrong or the endpoint has gone. Get the current URL from whoever runs the other end and update the door.
we couldn't reach them The other end is down or unreachable. Check with whoever runs it.

AIR raises this as an alert the first time a door starts failing, and then stays quiet about it — a channel that is down does not need to tell you a thousand times. The count on that alert is how many alerts have not got through since it broke. It resolves itself once the door delivers again.

Re-syncing a signing secret

signature_mismatch means AIR and the application on the other end are using different secrets. AIR signs every delivery; the other end checks the signature and refuses anything that does not match.

  1. Open the team's SDK door and reveal the signing secret.
  2. Give that value to whoever runs the receiving application. It goes into their environment as AIR_WEBHOOK_SIGNING_SECRET.
  3. Ask them to restart or redeploy so the new value is picked up.
  4. The next alert will get through. The deliveries line will change to arriving, and any open alert about the door resolves on its own.

Rotating is not the same as re-syncing

Rotating mints a new secret and immediately invalidates the old one. If the other end has not been given the new value first, you turn a broken channel into a broken channel with a different error. Re-sync first; rotate only when you actually want to revoke the old secret.

Developers on the receiving end: see webhooks. The SDKs verify signatures for you, and they verify against the raw request body — re-serialising the JSON before checking is the usual cause of a mismatch that looks like a wrong secret.

4. Was there enough information to route it?

Some alerts cannot be sent because AIR could not work out who they were about — so it could not work out whose overseer to tell.

You will see this as an alert saying a required piece of configuration was not supplied. It is not something you can fix from the interface. If you see it, report it: it means something upstream did not pass on who the alert concerned, and the fix belongs in AIR rather than in your settings.

Checking it worked

Once you have made a change, the fastest confirmation is the deliveries line on the door — it updates on the next delivery, and reads arriving with a timestamp when the route is healthy again.

You do not need to reproduce whatever triggered the original alert. Any event through that door proves the channel.