Skip to content
All articles
Security4 October 2020·3 min read

How to build a webhook: guidelines and best practices

Security work is mostly the business of removing footguns before someone finds them.

Paycux engineering

Security work is mostly the business of removing footguns before someone finds them. The interesting question is rarely whether an attack is possible — it is whether the ordinary path through your system makes it easy.

This piece walks through how we think about it at Paycux, what we have changed our minds about, and where the sharp edges are.

How to build a webhook

That brings us to how to build a webhook. Rotate on a schedule, not on an incident. A rotation path that has been exercised is a routine change; one that has never been used is an outage waiting for the worst possible moment.

Rotate on a schedule, not on an incident. A rotation path that has been exercised is a routine change; one that has never been used is an outage waiting for the worst possible moment.

Handling authentication: Signing webhooks and encrypting payloads

Consider handling authentication: signing webhooks and encrypting payloads. Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

  • Scope credentials to the smallest useful blast radius
  • Alert on the abuse you cannot prevent
  • Exercise the rotation path before you need it
  • Log the decision, not just the outcome

How to handle implementation with authentication

How to handle implementation with authentication deserves its own treatment. Rotate on a schedule, not on an incident. A rotation path that has been exercised is a routine change; one that has never been used is an outage waiting for the worst possible moment.

Blast radius is the metric that actually matters. A credential that can read one organization's data is an incident; the same credential scoped to every organization is a company-ending event, and the difference is a design decision made months earlier.

How to secure data in transit with authentication

Consider how to secure data in transit with authentication. Rotate on a schedule, not on an incident. A rotation path that has been exercised is a routine change; one that has never been used is an outage waiting for the worst possible moment.

Rotate on a schedule, not on an incident. A rotation path that has been exercised is a routine change; one that has never been used is an outage waiting for the worst possible moment.

Detection beats prevention when prevention is uncertain.

Sending events: Error handling, ordering, and duplicates

Sending events: Error handling, ordering, and duplicates deserves its own treatment. Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

Blast radius is the metric that actually matters. A credential that can read one organization's data is an incident; the same credential scoped to every organization is a company-ending event, and the difference is a design decision made months earlier.

Error handling and retry logic

Error handling and retry logic is where this gets concrete. Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

Handling event ordering‍ and duplicates

Handling event ordering‍ and duplicates deserves its own treatment. Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

Detection beats prevention when prevention is uncertain. If you cannot stop a class of abuse outright, make sure it produces a signal loud enough that someone sees it the same day.

Where this leaves us

The pattern repeats across every system we have looked at: the hard part is not the mechanism, it is keeping the mechanism honest as the surrounding assumptions change.

If you are working through the same problem and want to compare notes, the docs cover the mechanics and the console shows the behaviour on your own data.

Everything here, already built

Sign-in, enterprise SSO, directory provisioning, roles and an audit trail behind one API. Start with the quickstart and have a working sign-in this afternoon.

Start selling to enterprise customers

Create an account, point sign-in at Paycux, and get back to the part of the product that is actually yours.