Webhooks

Meet calls your server when something happens, so you do not have to poll.

A webhook endpoint is an https address on your server. Meet POSTs a signed JSON event to it. Events are scoped to the project and the mode of the key that made the endpoint: a test key gets test events, a live key live ones.

Add an endpoint#

curl "https://meet.respiresoft.com/api/v1/webhooks" \
  -H "Authorization: Bearer $MEET_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://app.acme.com/meet-webhook", "events": ["session.ended", "recording.ready", "transcript.ready"]}'

The answer has a secret that starts whsec_. It is shown once, so store it. Use "events": ["*"] for every event except chat.message, which you must ask for by name. You can have up to 20 endpoints for each project and mode. Send a test event any time: POST /api/v1/webhooks/{id}/test.

Receive and verify#

Verify the signature over the raw body before you trust anything. Code in Node, Python, PHP and Go is on Webhook events and signatures. Then answer with any 2xx quickly.

import express from 'express';
import { Meet } from '@respiresoft/meet';

const app = express();
app.post('/meet-webhook', express.raw({ type: '*/*' }), (req, res) => {
  const event = Meet.webhooks.constructEvent(req.body, req.get('Meet-Signature'), process.env.MEET_WEBHOOK_SECRET);
  console.log(event.type, event.data);
  res.sendStatus(204);
});
app.listen(3000);

Delivery rules#

• At least once. The same event can arrive twice. Remember the event id (also in the Meet-Event-Id header) and ignore repeats.
• Retries. Attempt 1 happens at once. If it fails, Meet tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. That is 7 attempts over about 20 hours. A 2xx is success. Anything else, a timeout or a redirect counts as failed.
• Redeliver. POST /api/v1/events/{id}/redeliver starts a fresh series for an event you missed.
• Where Meet sends. Only https addresses on the public internet. No localhost, .local, .internal or private addresses, no user and password in the address, and redirects are never followed. Meet connects to the address it resolved, so an address cannot be switched to a private one after the check.
• Time. Your endpoint has 10 seconds for each step and 15 seconds in all. Do the work later and answer first.
• Secrets. POST /api/v1/webhooks/{id}/roll-secret makes a new secret and the old one stops working at once.

Look at what happened#

GET /api/v1/webhooks/{id}/deliveries lists every attempt with its state. GET /api/v1/events lists events (filter with ?type=). The dashboard shows the same under Webhooks. Endpoint operations are on Webhook endpoints API.