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[bot]]

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```

[ldynia]

Thanks!

It would be nice if you could cast more light (examples) on the webhooks at your website, because it deserves attention.

1. Including description of how API consumer subscribes to the webhooks (registers its callback URL in the API producer system).
2. How API producer describes events that it sends to API consumer (using API's consumer callback URL).

Best!

[sujal-jain-activities]

Nice question, i would like to give answer of that,

1. What's AsyncAPI's stand on webhooks? AsyncAPI is designed for event-driven architectures and asynchronous APIs, which aligns perfectly with webhooks' event-driven and asynchronous nature. While AsyncAPI doesn't explicitly label a specific section as "webhooks" like OpenAPI does, its core design principles support webhook patterns well.
2. Is AsyncAPI suitable to document webhooks? Yes, AsyncAPI is suitable for documenting webhooks. The webhook pattern (where a service subscribes by providing a callback URL and later receives asynchronous events) can be modeled in AsyncAPI as:

The publisher service exposing channels that clients can subscribe to The message flow direction being clearly specified (from server to client) The server sending messages to the client's HTTP endpoint

You can model this by:

Defining your channels with appropriate publish/subscribe operations Specifying HTTP as the protocol for the client-side bindings Documenting the subscription process in your AsyncAPI document

3. OpenAPI vs AsyncAPI for webhooks? Both specifications can document webhooks, but they approach it differently: OpenAPI webhooks (introduced in 3.1.0):

Designed primarily for HTTP-based APIs with a dedicated webhooks section Better if webhooks are an auxiliary feature of a primarily request/response API More straightforward if you're already using OpenAPI for your main API

Here's an example of how to document a webhook using AsyncAPI:

webhook-asyncapi-example.txt

[nachiketmahale9]

1. My take on Webhooks?

• Webhooks are event-driven callbacks where a client subscribes to an event from a publisher service, providing a callback URL. The publisher pushes data asynchronously when the event occurs. For clear understanding consider a payment gateway (e.g., Stripe) that notifies your application when a payment succeeds by calling your provided webhook URL.

2. Is AsyncAPI suitable to document webhooks?

• Yes but only in some cases.

Use AsyncAPI if webhooks are part of a broader event-driven system (e.g., alongside Kafka, RabbitMQ, or Pub/Sub).

Use OpenAPI if webhooks are part of a REST API (e.g., requiring clients to register a callback URL).

Best usecase: Use OpenAPI for webhook registration and AsyncAPI for event payloads if both are needed. 🚀

3. Or, do you recommend using OpenAPI specification since it supports webhooks?

• partially yes based on conditions, OpenAPI is the better choice for documenting webhooks because it natively supports them.

OpenAPI is designed for REST APIs, including webhooks where a client provides a callback URL to receive events. AsyncAPI is better suited for message brokers (e.g., Kafka, RabbitMQ), not simple HTTP-based webhooks.

4. When to Use OpenAPI for Webhooks?

• If your API sends HTTP callbacks to client-provided URLs (e.g., Stripe sending payment notifications).

After reading this even if doubt persist , please let me know , I'll try to clarify it for better understanding.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: