5 ms·

Standard Webhooks: open-source tools and guidelines for sending webhooks

149 points by yurisagalov 3y ago

pyrolistical 3y ago
> While this specification does not dictate the structure, or impose any requirements, on the shape, format, and content of the payload it does offer recommendations Too loose to be a standard but better than nothing.
- tasn 3y ago
  Yeah, we don't call it a standard for that reason, here's the tagline: > Open source tools and guidelines for sending webhooks easily, securely and reliably We have been going back and forth about this. Though we purposefully made Standard Webhooks more like guidelines than a formal specification (note there's no mention of RFC2119, for example) so that it's easier to conform to without forcing implementations to have breaking changes. Even if it means you don't get the full benefits. I think people can get a lot of benefits even if they don't follow the whole thing, and it's our job to continue building tools to make it easier to build conforming implementations than non-conforming ones.
dwb 3y ago
I wondered, "whose standard?", and was pleasantly surprised to find a list of real names [1] on the website. Nonetheless, I do bristle at the semantic weight of the name despite the fact it's not attached to a relevant existing institution. [1]: https://www.standardwebhooks.com/#committee https://www.standardwebhooks.com/#committee
- paulddraper 3y ago
  idk man, no one bristles at the S&P 500.
  - dwb 3y ago
    ? That's obviously just a name, it's not making a claim.
simonw 3y ago
This is useful. I've been part of a team implementing webhooks in the past and there are a lot of difficult details you need to get right - things like responsible retries, authentication, thin-vs-fat hooks and server-side request forgery. This document covered all of them. Here's the SSRF bit for example: https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#server-side-request-forgery-ssrf https://github.com/standard-webhooks/standard-webhooks/blob/...
yawboakye 3y ago
webhooks were a phase we should have passed by now, not try to entrench with some standard. it’s a broken/obscure implementation of full duplex communications between two systems but thought up as if it were a luxury, auxiliary system whose downtime we should be able to tolerate. if we’re required to survive downtime of a webhook system, i think we’re right to ask: why are they there in the first place?
- Cyphase 3y ago
  What should replace them?
- paulddraper 3y ago
  what is your suggestion for duplex communication?
  - strken 3y ago
    I'm not totally anti-webhook or the person you replied to, but I'd prefer at-most-once delivery via something that establishes a reusable connection (grpc or even websockets?) and backed by an events endpoint like Stripe's where the client can read everything that would have been sent. That way the client can replay all the events at leisure and retries aren't the server's responsibility.
    - TheCycoONE 3y ago
      I also prefer events over a persistent connection for efficiency, but webhooks are far better when the client is using a function as a service model.
      - strken 3y ago
        My experience is that if your server doesn't retry webhooks then you could be doing something more efficient, and if it does retry webhooks then that indicates it's important not to miss anything and you should use persistent events rather than relying on bug-prone "if there's a 200, drop the event from the DB" webhook retries from the server. I do think there's an argument for the interoperability of webhooks for integrating different services. I'm skeptical that they're the best choice from a purely technical perspective.
stephen123 3y ago
Looks great. What are people using to store and send retries?
- orangepanda 3y ago
  Plain ol’ sql
  - paulddraper 3y ago
    as in, a database queue?
ultrasaurus 3y ago
This is also a really good summary of "what to think about while implementing webhooks" -- personally I wish we had thought of doing "thin" webhooks in an implementation I was a part of.
paulddraper 3y ago
Question: Why do so many webhooks use HMAC signatures for authorization? For everything else in APIs, people are perfectly happy to use API tokens/secrets directly in headers. Why don't webhooks directly share secrets, instead of HMAC signatures? Like, I understand the advantages of HMAC, but for some reason it seems to be that webhooks are unique in their usage of it.
- rkeene2 3y ago
  The only advantage is that it validates that the send composed the message in the case without a shared secret (which is not what the article appears to advocate for). A shared secret alone, or an HMAC based on a shared secret, just means any party with the secret -- which could include anyone who would need to verify it -- composed the message. I generally don't do what's advocated for in the article because it doesn't make a lot of sense, I do either: - A shared secret - A signed and HMACed payload with asymmetric key
  - rkeene2 3y ago
    Although this ONLY holds if you're using HTTPS -- which is a separate thing, so maybe they're considering that you might not use HTTPS.
    - js2 3y ago
      In my case I'm using mTLS and verifying the CN of the client cert. This is for an internal service. I'm also surprised the recommended headers doesn't include the event type. I found it beneficial to be able route the event before parsing the body and w/o having to use different endpoints.
AustinBGibbons 3y ago
Good sign to me is one of the steering members is Tom Hacohen founder of Svix (webhooks-as-a-service). We're adopting them where I work and everything from them has been solid. I know he's seen a lot of different use cases and will have good consideration for the schema they define in their spec file.
- tasn 3y ago
  Thanks a lot Austin! All of us on the committee have a lot of first hand experience with webhooks, which we then distilled into the spec. :P
- tonyhb 3y ago
  Hard agree, they're a great team who have more knowledge in this space than almost anyone. The spec is great and makes a ton of sense.
kisamoto 3y ago
I'm curious as to why webhooks are becoming a defacto standard for triggering events between isolated systems. Why not have a dedicated event bus (could be - but not limited to - kafka, NATS etc.) where remote systems connect to dedicated event queues? Push a message onto the queue which is picked up by the remote system. Authentication is handled by the event bus which can also act as a storage for message (re)delivery. Partitioned by customer ID for separation of concerns etc. Anything immediately obvious why this wouldn't be a preferred option or is it because HTTP is just easier to implement across systems?
- nerdponx 3y ago
  > dedicated event bus A webhook is "peer-to-peer" and uses the existing HTTP infrastructure that's already in your application. Whereas an event bus is "centralized" and requires a third service to run/maintain/design. I'd like to avoid that if possible. Also webhooks make a lot of sense for communication between organizations, which you can't do with a centralized event bus (unless someone is out there running a global event bus that I'm not aware of). Let's say I'm using Managed Service Foo hosted by a third party, and I want to trigger some event in my own system whenever certain things happen in side Managed Service Foo. How else do you expect me to receive those events? Surely a webhook is a lot easier than figuring out an event bus to be shared across our two organizations.
theogravity 3y ago
The signature format is just weird. Why not include it as part of the request headers? Edit: It seems to also have a header version. Not sure why there's two different ways to pass a signature here.
- tasn 3y ago
  It's only passed as a header. Where did you see the other way of passing it? We'll clarify the spec if confusing.

149 points by yurisagalov 3y ago

> While this specification does not dictate the structure, or impose any requirements, on the shape, format, and content of the payload it does offer recommendations Too loose to be a standard but better than nothing.

tasn 3y ago
Yeah, we don't call it a standard for that reason, here's the tagline: > Open source tools and guidelines for sending webhooks easily, securely and reliably We have been going back and forth about this. Though we purposefully made Standard Webhooks more like guidelines than a formal specification (note there's no mention of RFC2119, for example) so that it's easier to conform to without forcing implementations to have breaking changes. Even if it means you don't get the full benefits. I think people can get a lot of benefits even if they don't follow the whole thing, and it's our job to continue building tools to make it easier to build conforming implementations than non-conforming ones.

dwb 3y ago

I wondered, "whose standard?", and was pleasantly surprised to find a list of real names [1] on the website. Nonetheless, I do bristle at the semantic weight of the name despite the fact it's not attached to a relevant existing institution. [1]: https://www.standardwebhooks.com/#committee https://www.standardwebhooks.com/#committee

paulddraper 3y ago
idk man, no one bristles at the S&P 500.
- dwb 3y ago
  ? That's obviously just a name, it's not making a claim.

simonw 3y ago

This is useful. I've been part of a team implementing webhooks in the past and there are a lot of difficult details you need to get right - things like responsible retries, authentication, thin-vs-fat hooks and server-side request forgery. This document covered all of them. Here's the SSRF bit for example: https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#server-side-request-forgery-ssrf https://github.com/standard-webhooks/standard-webhooks/blob/...

yawboakye 3y ago

webhooks were a phase we should have passed by now, not try to entrench with some standard. it’s a broken/obscure implementation of full duplex communications between two systems but thought up as if it were a luxury, auxiliary system whose downtime we should be able to tolerate. if we’re required to survive downtime of a webhook system, i think we’re right to ask: why are they there in the first place?

Cyphase 3y ago
What should replace them?
paulddraper 3y ago
what is your suggestion for duplex communication?
- strken 3y ago
  I'm not totally anti-webhook or the person you replied to, but I'd prefer at-most-once delivery via something that establishes a reusable connection (grpc or even websockets?) and backed by an events endpoint like Stripe's where the client can read everything that would have been sent. That way the client can replay all the events at leisure and retries aren't the server's responsibility.
  - TheCycoONE 3y ago
    I also prefer events over a persistent connection for efficiency, but webhooks are far better when the client is using a function as a service model.
    - strken 3y ago
      My experience is that if your server doesn't retry webhooks then you could be doing something more efficient, and if it does retry webhooks then that indicates it's important not to miss anything and you should use persistent events rather than relying on bug-prone "if there's a 200, drop the event from the DB" webhook retries from the server. I do think there's an argument for the interoperability of webhooks for integrating different services. I'm skeptical that they're the best choice from a purely technical perspective.

stephen123 3y ago

Looks great. What are people using to store and send retries?

orangepanda 3y ago
Plain ol’ sql
- paulddraper 3y ago
  as in, a database queue?

ultrasaurus 3y ago

This is also a really good summary of "what to think about while implementing webhooks" -- personally I wish we had thought of doing "thin" webhooks in an implementation I was a part of.

paulddraper 3y ago

Question: Why do so many webhooks use HMAC signatures for authorization? For everything else in APIs, people are perfectly happy to use API tokens/secrets directly in headers. Why don't webhooks directly share secrets, instead of HMAC signatures? Like, I understand the advantages of HMAC, but for some reason it seems to be that webhooks are unique in their usage of it.

rkeene2 3y ago
The only advantage is that it validates that the send composed the message in the case without a shared secret (which is not what the article appears to advocate for). A shared secret alone, or an HMAC based on a shared secret, just means any party with the secret -- which could include anyone who would need to verify it -- composed the message. I generally don't do what's advocated for in the article because it doesn't make a lot of sense, I do either: - A shared secret - A signed and HMACed payload with asymmetric key
- rkeene2 3y ago
  Although this ONLY holds if you're using HTTPS -- which is a separate thing, so maybe they're considering that you might not use HTTPS.
  - js2 3y ago
    In my case I'm using mTLS and verifying the CN of the client cert. This is for an internal service. I'm also surprised the recommended headers doesn't include the event type. I found it beneficial to be able route the event before parsing the body and w/o having to use different endpoints.

AustinBGibbons 3y ago

Good sign to me is one of the steering members is Tom Hacohen founder of Svix (webhooks-as-a-service). We're adopting them where I work and everything from them has been solid. I know he's seen a lot of different use cases and will have good consideration for the schema they define in their spec file.

tasn 3y ago
Thanks a lot Austin! All of us on the committee have a lot of first hand experience with webhooks, which we then distilled into the spec. :P
tonyhb 3y ago
Hard agree, they're a great team who have more knowledge in this space than almost anyone. The spec is great and makes a ton of sense.

kisamoto 3y ago

I'm curious as to why webhooks are becoming a defacto standard for triggering events between isolated systems. Why not have a dedicated event bus (could be - but not limited to - kafka, NATS etc.) where remote systems connect to dedicated event queues? Push a message onto the queue which is picked up by the remote system. Authentication is handled by the event bus which can also act as a storage for message (re)delivery. Partitioned by customer ID for separation of concerns etc. Anything immediately obvious why this wouldn't be a preferred option or is it because HTTP is just easier to implement across systems?

nerdponx 3y ago
> dedicated event bus A webhook is "peer-to-peer" and uses the existing HTTP infrastructure that's already in your application. Whereas an event bus is "centralized" and requires a third service to run/maintain/design. I'd like to avoid that if possible. Also webhooks make a lot of sense for communication between organizations, which you can't do with a centralized event bus (unless someone is out there running a global event bus that I'm not aware of). Let's say I'm using Managed Service Foo hosted by a third party, and I want to trigger some event in my own system whenever certain things happen in side Managed Service Foo. How else do you expect me to receive those events? Surely a webhook is a lot easier than figuring out an event bus to be shared across our two organizations.

theogravity 3y ago

The signature format is just weird. Why not include it as part of the request headers? Edit: It seems to also have a header version. Not sure why there's two different ways to pass a signature here.

tasn 3y ago
It's only passed as a header. Where did you see the other way of passing it? We'll clarify the spec if confusing.