Set up team webhooks

Team webhooks tell your own tools when someone on your team finishes a lab or earns a badge.

Before you start

• You need a Team plan that is active. If the plan lapses or the team is suspended, nothing is sent until it is active again.
• Only the team's owner can manage webhooks, because they carry the members' activity out of IT Bible. Admins and members cannot see or change them.
• Your receiving address must be a public https address. Addresses with a user name or password in them are refused, because the signature already proves who is calling.
• A team can have up to 5 webhooks.

Add a webhook

1. Open your team's management page, then choose Webhooks.
2. Choose Add a webhook.
3. Give it a name. Only you see the name.
4. Enter the address IT Bible should call.
5. Choose the events you want. See Events and payloads for what each one sends.
6. Save. The next page shows the signing secret. Copy it into your receiving service. You can show it again later on the same page.

Test it

Press Send a test event. A ping event is sent to your address and appears under Recent deliveries a moment later. A status of Delivered means your server answered with a 2xx. If it shows Failed, the row says what went wrong, such as the HTTP status your server gave.

Write your receiver to check the signature before you rely on it.

What your members see

Members of the team see a notice on the team page that the team has a webhook turned on and can be told when they finish a lab or earn a badge. The invitation page also mentions that a team can set one up. A member who does not want this can leave the team.

Keeping it healthy

• Answer quickly with a 2xx and process the event afterward.
• Use the id of each request to ignore a repeat. Retries send the same id.
• Replace the secret from the webhook's page if it might have leaked. The old secret stops working at once.
• Turn a webhook off when you retire the receiving service, or delete it to remove its history too.
• If a receiver keeps failing, the site's administrators can also turn your webhook off. You can turn it on again from your page.

Labs your team uploads

Completions of your team's own labs are reported with the same member.lab_completed event, with lab.private set to true and no badge or points. See Upload your own labs.