Webhooks support

[ldynia]

Context

Webhooks are event-driven, and communication between webhook-integrated services is asynchronous.
A standard webhook flow follows client service subscribing to the publisher service by sending to the publisher a callback URL to be notified about an event that the publisher produces.

Obviously, AsyncAPI allows to document event-driven services that communicate asynchronously.

Question

I didn't see any examples of webhooks being documented by AsyncAPI, and the OpenAPI specification supports webhooks.

My questions are as follows:

1. What's your stand on webhooks?
2. Is AsyncAPI suitable to document webhooks?
3. Or, do you recommend using OpenAPI specification since it supports webhooks?

Thanks for clarification

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[Shreshtthh]

Great questions

1. What's my stand on webhooks? Webhooks are event-driven and asynchronous, making them an excellent pattern for systems that need real-time notifications. They follow a publish/subscribe model where the client subscribes by registering a callback URL where they'll receive event notifications.

2. Is AsyncAPI suitable for documenting webhooks? Yes, AsyncAPI was designed for event-driven architectures and is well-suited for webhooks. While it's commonly used for message brokers (Kafka, MQTT), it supports HTTP-based webhooks too with appropriate protocol bindings.

3. Should you use OpenAPI instead? It depends on your architecture:

   • Use OpenAPI if your system is primarily RESTful with occasional webhook callbacks
   • Use AsyncAPI if your system is predominantly event-driven or uses multiple protocols

4. How to document a webhook using AsyncAPI:

asyncapi: '2.6.0'
info:
  title: ConTracker Webhook API
  version: '1.0.0'
  description: Webhook notifications for ConTracker platform events
servers:
  production:
    url: https://api.contraacker.com
    protocol: http
    description: Production server
    bindings:
      http:
        type: request
channels:
  /webhooks/bid-events:
    subscribe:
      message:
        $ref: '#/components/messages/BidPlaced'
      bindings:
        http:
          method: POST
          bindingVersion: '0.1.0'
components:
  messages:
    BidPlaced:
      name: bidPlaced
      contentType: application/json
      payload:
        type: object
        properties:
          bidId:
            type: string
            description: Unique identifier of the bid
          tenderId: 
            type: string
            description: The tender being bid on
          amount:
            type: number
            description: Amount of the bid in MATIC
          bidder:
            type: string
            description: Address of the bidder
          timestamp:
            type: string
            format: date-time
            description: Time when the bid was placed```