DEV Community

Cover image for Part 5: I wrote the guide that explains how an API calls you back.
Joyce Foster
Joyce Foster

Posted on

Part 5: I wrote the guide that explains how an API calls you back.

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.

https://github.com/joycefoster642/Troyal-API-Docs

Top comments (2)

Collapse
 
joycefosterr profile image
Joyce Foster •

This is Amazing work!😍❀️🩷✨🎊🌸πŸ₯Ήβ€οΈπŸ©·πŸŽŠπŸ₯³πŸŒΈ

Collapse
 
docsalive profile image
DocsAlive Team •

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.