How does one interact with an OpenAPI-defined webhook?

Question

Reading the OpenAPI webhook spec, I'm having trouble understanding how would I implement / interact with an OpenAPI defined webhook. My main sources are:

• https://spec.openapis.org/oas/latest.html#openapi-object (spec, webhooks field)
• https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml (example)

Let's take a look at this example (I trimmed the irrelevant parts)

openapi: 3.1.0
webhooks:
  newPet:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

My questions:

• Does this mean when this newPet event happens (what this event means, is implementation detail according to the spec, as far as I can see), this server may send a POST request with a Pet body, and expects a response with 200 status code?
  • If no,
    • Then what does this mean?
  • If yes,
    • To what URL is this request being sent to?
    • Can the user of this API somehow register a URL where this request should be sent to?
    • If the user of this API no longer wishes to receive POST requests related to the newPet event, how do they unsubscribe?
    • Is the protocol still HTTP (I'm 99% sure, just to be safe)?

Answer 1

Does this mean when this newPet event happens (what this event means, is implementation detail according to the spec, as far as I can see), this server may send a POST request with a Pet body, and expects a response with 200 status code?

Yes.

To what URL is this request being sent to?

This URL is defined somewhere outside the API. For example, the API vendor can provide a developer portal where developers can subscribe to the webhooks they need and configure the target URLs.

Can the user of this API somehow register a URL where this request should be sent to?

See above.

If the user of this API no longer wishes to receive POST requests related to the newPet event, how do they unsubscribe?

See above. Webhook subscription management is supposed to happen somewhere outside the API.

Is the protocol still HTTP (I'm 99% sure, just to be safe)?

OpenAPI Specification does not mention this, but it's safe to assume HTTP or HTTPS. Some vendors limit outgoing webhook URLs to HTTPS only for security reasons.