# Webhook API

Mattermost, Rocket.Chat, Zulip, Google Chat, Webex or a chat you built yourself: write one small
bridge, and your team plays the same games as on Slack, Discord and Telegram.

**Private beta.** Hijinks is not public yet, and custom-platform workspaces open with everything
else at launch. These pages document the contract so you can plan a bridge; details may change
before then. <a href="https://www.hijinks.team/#early-access">Join the waitlist</a> to hear first.

## How it works

Hijinks never talks to your chat directly. It talks to a **bridge**: a small HTTP service you run
next to your chat tool. Both directions are JSON over HTTPS, signed with one secret per workspace.

1. In the Hijinks dashboard you connect a custom platform: a name, your bridge's HTTPS URL (or
   none, for a bridge that [polls](/polling)) and a language. You get a signing secret (shown once) and your inbound URL,
   `https://api.hijinks.team/hooks/<workspace id>`.
2. A member types `/hijinks start` in your chat. Your bridge POSTs a signed `command` event to the
   inbound URL and gets `202` back straight away.
3. Hijinks POSTs signed events to your bridge: a `message.create` for the game's start card. Your
   bridge posts it and remembers which chat message `message.id` became. Each question then
   arrives as a `message.update` of that same message, with buttons.
4. A member presses a button. Your bridge sends an `action` event with the button's opaque
   `action` string, untouched. Hijinks redraws the game's message with `message.update` (the
   answer count), then the reveal, the next question and the final board.

Everything a bridge needs is in the
<a href="/webhooks/openapi.yaml">OpenAPI 3.1 contract</a>: every event, every field, an
example of each, and every error. Point a code generator or a JSON Schema validator at it, or
browse it here as the [API reference](/api).

## Where to next

- [Quickstart](/quickstart): start a round from a terminal with curl, before writing any bridge
  code.
- [Verify signatures](/signatures): the header format, and drop-in code for Node, Python and Go.
- [Events](/events): every event in both directions, how to render a message, retries and
  ordering.
- [Reference bridge](/reference-bridge): a complete Mattermost bridge in one file, to copy for
  any other chat, and an email to send your IT team.
- [What works over a bridge](/bridged-chats): every game and team feature, and what differs from
  Slack and Discord.
- [What a bridge sends us](/data-flow): the data that passes between your chat and Hijinks.
- [Polling](/polling): for a chat server that cannot be reached from the internet.

## Building a bridge for your chat?

Custom platforms open with the rest of Hijinks at launch, on the same plans: flat per workspace,
never per user. <a href="https://www.hijinks.team/#early-access">Join the waitlist</a>; the form asks
which chat you use. Questions about the API: support@hijinks.team.