Webhook doc seems outdated

Frappe Framework
1

The webhooks documentation at Webhooks seems outdated.

I tried to include line items, and using any of:

items
doc.items
json.dumps(doc.items)

won’t work (Errors or outputting

<built-in method items of _dict object at 0x7f7caa007400>

This seems to be the result of outputting json with jinja templates (probably due to security questions?).
Anyway, a documentation update might help people looking for documentation.

Other than that, webhooks are fun-to-use machinery pistons. :smiley:

2

Share complete webhook doc data.

The exact jinja2 template if it is used.

3

Thank you very much @revant_one, that was a very nice challenge!

There is no need to share the complete webhook doc data nor the exact jinja2 template in this case, because the problem at hand is UI semantics and thus documentation semantics, as you’ll see.

The problem is how to funnel any JSON object through Jinja. In fact, you can’t, because the diverse type juggleries (including serialization and deserialization) on the path from data to be sent to data received on the other end get in the way.
That’s why the doc says: “If your request structure is based on JSON, you can insert fields from the document using jinja templating (make sure to wrap your fields with double-quotes).”

This means, that the UI and the doc say “JSON”, but in fact, the JSON mechanics of the webhook are misnamed and indeed misleading, because in fact its not JSON, but just “You can create any strings from the doctype fields using jinja2 templating”.

The specificity of JSON over strings is putting together, and recursively so, different object types into one serializable-to-string object whose serialized form can be restored into the compound object containing different types.

But nothing of this specificity is left in the functionality of the webhook: You have to pick your fields from the JSON object yourself (“manually”) and totally build the serialized “JSON” string yourself.

When I read “JSON” in the UI, I expect to be able to put some compound JSON object or sub-object into some variable-or-so and benefit from some kind of automatic deserialization. But this was totally impossible.

I repeatedly tried to send a quite minimal sales manually entered into an each time new SO and send it to a similarly minimalistic flask receiver printing out the data of the POSTs sending “JSON” request structures, which produced b’…’ strings of the request html’s data on the console log which I was watching.

  • There was no default to send the whole SO object as automatically serialized JSON.
  • Using Jinja templates in the JSON named webhook form made the webhook machinery complain (e.g. webhook log showed errors) about anything other than non-compound objects put into the {{ }} of the manually built template string.
  • The field “fields” of the SO object produced errors or the flattened technical object string representation I showd in my post.

At this point I was satisfied with the results which I could use with webhooks.
I know I can iterate over lists with Jinja, but didn’t try it, because I’m confident that I’d get it to work. That’s why I expressed my fun using webhooks in my comment.

But what’s the point to call it JSON in UI and doc if all you can do is just build strings (e.g. picking JSON tree leafs yourself and deserialize the sub-object manually) yourself?

The section title is named (in DocField terminology: labeled) “Webhook Data” and the field “JSON Request Body”. So it’s there, but hidden. It shows the intent and the knowledge the user should have if she wants to build against a JSON receiver. But there is nothing JSON in what the webhook does.
It just allows you to build any string with Jinja2, and deserialized JSON happening to be a string, you can build such a string.

So that’s a UI and documentation bug as far as I am concerned. It’s also a bit of overhyping a nonexisting (scope: at this place specifically) JSON capability of the framework, capability which in fact has to be in the low-code user.

Anyway, I still like it because with the existing capabilities you can indeed build ANY string yourself, which can be very useful for many other receiving listeners, DIY machinery included, and I consider it a great advantage to be able to do exactly that.

My suggestion would be to name it Jinja Template instead of JSON in the selector on top of the webhook form AND at the bottom field, and maybe to build a real JSON capable webhook sender option as a third option (e.g. FORM, Jinja, JSON).

4

In case anyone needs it, here is a link to jinja documentation:
https://jinja.palletsprojects.com/en/3.1.x/templates/

Anyway, with all that I wrote, I’m still not sure if I missed something in the Webhook API’s capabilities, though.