Alert channels

A channel is a place alerts go: a set of email addresses, a Slack channel or a signed webhook. Every channel that’s on gets every alert your alert level sends, unless a site picks its own channels.

You manage channels in Alerts › Where. Add one with Add channel. Open a channel to see its delivery log. The owner and people who can edit all sites can add, change and remove channels.

Email

Choose Add channel, then Add email. An email channel can send to:

• People: members of the account. Only people with a verified email address can be ticked.
• Other addresses: anyone else, one per line, such as a shared inbox.

A new account starts with one email channel, Email me, that sends to the owner once their address is verified.

People with access to selected sites only never get channel emails. They can use Email me about this site instead (see Alert level and per-site alerts).

Each of the other addresses gets a link to confirm first. Until it’s confirmed, the address shows Waiting for confirmation and gets nothing.

When an alert about a new or worse incident comes with a robots.txt or ads.txt change, the email shows up to 10 of the changed lines, so you can see what moved without opening SEOComet.

Slack

Alerts reach Slack through an incoming webhook. The quickest way to set one up is Add to Slack:

1. Choose Add channel, then Add to Slack.
2. In Slack, pick the workspace and the channel, and press Allow.

You come back to SEOComet with a new channel named Slack and the channel’s name. The SEOComet for Slack page covers what it posts, how to remove it and what it stores.

You can also paste a webhook URL yourself:

1. In Slack, add the Incoming Webhooks app, pick the channel and copy the URL it gives you. It starts with https://hooks.slack.com/services/.
2. In SEOComet, choose Add channel, then Paste a Slack webhook URL, and paste it into Slack webhook URL.

Slack messages include the same changed lines as email.

Signed webhooks

A signed webhook sends each alert to your own server, so you can feed it into another tool. Choose Add channel, then Signed webhook, and enter an Endpoint URL. It must start with https://.

Every alert is a JSON POST. The body has the event and when it happened, the account, the site, the check, the incident with its severity and status, and the issue’s code and message.

When you add the webhook, or make a new secret, SEOComet shows the signing secret once. Copy it then and keep it on your server. If you lose it or think it leaked, open the channel and choose Make a new signing secret. The old secret stops working straight away.

Verifying signatures

Each request carries these headers:

• X-SEOComet-Signature: sha256= and the hex HMAC-SHA256 of the timestamp, a full stop and the raw body, keyed with the signing secret.
• X-SEOComet-Timestamp: when it was signed, in Unix seconds. Refuse anything more than 300 seconds off your clock, so an old request can’t be replayed.
• X-SEOComet-Delivery: the delivery id. Retries keep it, so skip an id you’ve already handled.
• X-SEOComet-Event: incident.opened, incident.escalated, incident.resolved, incident.still_open or test, and for Google update alerts google_update.started or google_update.ended.

This is the check the app shows on a webhook channel’s page:

// Node.js, with the raw request body as a string
const crypto = require('crypto');

function isFromSEOComet(req, rawBody, secret) {
  const timestamp = req.headers['x-seocomet-timestamp'];
  const signature = req.headers['x-seocomet-signature'];
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!timestamp || !signature || age > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // timingSafeEqual throws unless both are the same number of bytes.
  const received = Buffer.from(signature);
  const wanted = Buffer.from(expected);

  return received.length === wanted.length &&
    crypto.timingSafeEqual(received, wanted);
}

Compare the signature over the raw body as it arrived. Parsing the JSON and turning it back into text can change it.

Testing a channel

Send test sends a sample alert, marked as a test, through the real channel. Use it after adding a channel, or to check a webhook after changing your server. You can test a channel even while it’s off. A test is never retried and never counts toward turning a channel off.

When a delivery fails

A delivery counts as sent when the channel answers with any 2xx status. Otherwise SEOComet tries again, up to 6 attempts in all. The waits before each retry are a minute, 5 minutes, 15 minutes, an hour and 4 hours.

Some failures end the delivery at once, without retries: a redirect, since redirects aren’t followed; a 410, which says the address is gone; and an address inside a private network, which SEOComet won’t send to. An email channel with nobody to email fails the same way.

If 10 deliveries in a row fail, after their retries, the channel is turned off so it stops piling up failures. The owner and people who can edit all sites get an email about it. Fix the address, then use Turn on on the channel.

Which plans have which channels

Free sends alerts by email only. Pro and Business add Slack and signed webhooks.

If you move to a plan without Slack or webhooks, those channels are turned off. They come back on when you move to a plan that has them.

See pricing for what each plan includes.