What if your API could call you?
That's what webhooks do, and I just wrote the webhooks guide for Troyal, my fictional royalty-tracking API. This follows the error codes guide, the changelog and the Jira board from last time.
An API mostly consists of you asking it for things. Webhooks are designed to flip that narrative so that Troyal tells you when something happens, like a royalty statement being generated, and so a developer doesn't have to keep checking.
The guide covers:
- Setting up an endpoint and getting a signing secret.
- The five events Troyal can send.
- What an event looks like (the payload).
- How to check a request really came from Troyal, with a short code example.
- What happens when a delivery fails, and how retries work.
The part that took the most care was the signature check. One wrong step there could leave a developer's system open to fake requests, so I kept the explanation short and the code example small.
Everything is public on GitHub.
Next up for Troyal: ownership splits and royalty statements in the OpenAPI spec, then a docs site.
I'm also open to Technical Writing positions, so if your team is hiring, I'd love to hear from you.
Troyal is fictional. The documentation is real.
Top comments (2)
This is Amazing work!πβ€οΈπ©·β¨ππΈπ₯Ήβ€οΈπ©·ππ₯³πΈ
Signature verification is exactly where a small example benefits from being explicit: verify against the raw request body before parsing or transforming it, and compare signatures in constant time. I'd also mention deduplicating event IDs, since retrying deliveries can otherwise make one royalty statement look like two.