Developers

Webhooks

Let Chaos tell your own server when a response arrives or a form opens or closes.

A webhook is an address on your server that Chaos calls when something happens. They are optional. Chaos and connected apps work fully without them.

What Chaos can tell you

Response submitted: someone finished a form or a quiz.
Response graded: you changed the marks of a quiz answer.
Published, Closed and Reopened: a form or quiz changed state.

Add a webhook

Open Connections in the sidebar. Webhooks is below your connections.
Press New webhook and enter your server's address. It must start with https://.
Tick the events you want.
Choose All my forms and quizzes or Only the ones I choose.
Press Create webhook, then copy the signing secret into your server's settings. Chaos shows it once.
Press Send test to check that your server receives it and accepts the signature.

By default Chaos sends ids, counts, scores and times, never what people answered. Tick Include answers and respondent names only if your server may keep personal data. Webhooks made by a connected app never include answers.

Signatures and secrets

Every delivery is signed with the webhook's secret, so your server can check it came from Chaos and is recent. New secret makes a new one. The old secret keeps working for 24 hours so you can switch without missing anything.

Chaos only calls public addresses. Addresses inside a private network are refused.

History and failures

Delivery history lists recent deliveries with their result. Press Resend to send one again.
If your server does not answer, Chaos tries again for about 15 hours, waiting longer each time.
After 25 failures in a row the webhook is switched off and you get a notification. Fix your server, then press Resume.
Pause stops deliveries until you resume. Delete removes the webhook and its history.

Developers: the payload format and how to check a signature are in the webhook document, version 1.