Integrations and webhooks

Admin → Integrations lists everything your organisation can connect to, whether each is in use, and what is not built yet. Admin → Webhooks is where you add endpoints. Owners and admins can open both.

Approve from chat#

With the Slack or Microsoft Teams app connected, each approver gets a request as a direct message, never a channel post, with Approve and Decline buttons and a link to the full request. Every copy of the message updates once the request is decided, expires or is withdrawn, wherever that happened. Email still goes out as well, so chat is never the only route to anybody.

1. 1

   Slack

   Choose Add to Slack under Approve from chat and finish the install in Slack. Approvers are matched to their Slack account by email address. You can add more than one workspace.

2. 2

   Microsoft Teams

   Choose Download the app package and upload it in the Teams admin centre. Each approver then adds the app from their own chat; the card shows how many have. A Teams app can only message somebody who has added it.

Either card says Not yet available when the app has not been configured on this deployment.

Email and browser notifications#

• Email. Approvers are emailed each request. For a low or medium-risk request that no ethics rule flagged, the email carries a link that opens the request without signing in; the approver still presses Approve or Reject on the page. High and critical risk, flagged requests, and organisations that require single sign-on get a plain link behind sign-in.
• Browser notifications. Each person turns them on for their own browser or phone in their settings; on an iPhone, only once the app is added to the home screen. Tapping one opens the request as the email would. See Your inbox and notifications.

What each person is notified about, and how, is theirs to choose in Your settings, except for the events that may not be muted.

Webhooks#

A webhook sends an HTTPS POST to an address you choose whenever something happens. Deliveries are queued and retried on their own, so a publish never waits on your endpoint or fails because of it.

Add an endpoint

1. 1

   Choose a format

   Standard JSON is the signed envelope, for anything you have built. Slack posts a native message to a channel: paste the URL of a Slack Incoming Webhook. Microsoft Teams posts an Adaptive Card: paste the URL from the Workflows app's *Post to a channel when a webhook request is received* template.

2. 2

   Paste the URL

   It must start with https:// and be on the public internet; addresses inside a private network are refused.

3. 3

   Choose events

   Tick the events you want, or leave them all unticked to receive every event, including any added later.

4. 4

   Copy the signing secret

   It is shown once, when the endpoint is created, and cannot be retrieved afterwards. If you lose it, remove the endpoint and add it again.

Events

Individual verdicts and replies are recorded in the audit log rather than sent; a channel hears when the answer is in. Actions a gate rule allowed are counted, not sent: only a refusal, gate.denied, is.

Signing

Every delivery carries a Deliverd-Signature header: a timestamp and an HMAC-SHA256 of the timestamp and the raw body, keyed with the endpoint's secret. Check it on every delivery, because the address is all anyone needs to send convincing fakes. Slack and Teams ignore it. The developer docs show how to verify it: Webhooks and callbacks.

Retries and pausing

• Any 2xx answer counts as delivered. Answer quickly and do the work afterwards: a request times out after ten seconds. Redirects are not followed.
• Anything else is tried again with growing gaps, five attempts in all, except a 4xx other than 408 or 429, which would fail the same way again.
• After twenty failures in a row the endpoint is paused and the page says why. Fix the endpoint, then choose Resume. You can also pause an endpoint yourself.

Testing

Each endpoint has Send test: choose an event and it is posted at once, signed like any other, marked test: true, with obviously fake ids. The answer your endpoint gave appears beside the button. A test is never retried and never counts toward the failures that pause an endpoint. Recent deliveries, at the foot of the page, shows the last 20 attempts and what came back.

Posting events to a Slack or Teams channel this way is separate from the chat apps above, which message approvers directly.