Forum Discussion

alexphelps's avatar
alexphelps
Occasional Visitor
25 days ago

Webhooks and Inheriting Schemas

I've been working on building webhook documentation for our project that uses Open API Spec 3.1 (built using DRF Spectacular). 

Background

We have versioned webhooks that follow our API schemas. The idea is simple, if you subscribe to a order.created webhook, we'll send you the same data in a webhook as you would get from calling the /api/orders/123/ to retrieve it. More detail in our docs. Our structure is similar to what you see at stripe. 

Webhook structure goes as follows:

{
"object": "<object>",   // ie order/cart/user etc so you know what type of object you're receiving
"data": "<object data>",  // object data (the api schema...)
"event_id": "<unique event id>", 
"event_type": "<event type>",  // ie order.created
"webhook": "<webhook info>",   // basic webhook schema
"api_version": "<webhook api version"  // API version controlling the schema structure of the data
}

The schemas (serializers) for this are powered by DRF serializers which are the base for the all schemas. This has worked wonderfully for us, gives us versioned webhooks and provides an upgrade path following our API schemas and relatively clean/clear consistent architecture with not a lot inconsistency issues. 

Attempt to Document Webhooks using Open API Spec 3.1

Initially, I thought I could use the schema of the objects to inherit from the base schemas for the "data", and would be easy, but that's not the case. 

Using  { "$ref": "#/components/schemas/XYZ} does not actually pull in all of the schema elements. I tried all of the variations but "readOnly" properties don't show and there are many nested schemas that use these. 

I've also tried many ways of making a "deep copy" of the base schema and copying it over the webhook, removing "readOnly", etc but just looks like a deeper and deeper rabbit hole of the wrong way to go about this.

First attempt at a webhook schema generator on github in our docs.

A way to reference a Response schema, or entire schema as readOnly?

It turns out, I actually need a link to the full response format of a schema or just the entire schema and nested schemas as readOnly.

Is that possible or antithetical to core concepts?


Links to our schemas
- https://github.com/29next/developer-docs/tree/main/static/api/admin


Any guidance or can see where I might be going wrong?

No RepliesBe the first to reply