Secure Webhooks: more examples

[mmahut]

Secure webhooks page needs more examples in different languages.

Lite version of the example, showcasing minimal web app with the signature verification can be contributed to https://blockfrost.dev/docs/start-building/webhooks/webhooks-signatures#using-sdk.

The whole example (with printing info from the received event payload) can be contributed to https://blockfrost.dev/docs/start-building/webhooks/using-webhooks#process-a-webhook-request

Signature Verification

The example has to showcase how to implement webhook endpoint including webhook signature verification. If the function for verification (named verifyWebhookSignature or verify_webhook_signature depending on the language conventions) is missing in the Blockfrost SDK for the language you need to implement it and open PR for the SDK. For full list of all available SDKs see https://blockfrost.dev/docs/sdks.

Basics of the signature verification are explained here https://blockfrost.dev/docs/start-building/webhooks/webhooks-signatures#verifying-the-signature-manually, but always crosscheck with reference implementations.

Reference implementation of the signature verification:

• Python https://github.com/blockfrost/blockfrost-python/blob/master/blockfrost/helpers.py#L18
• Typescript/Javascript https://github.com/blockfrost/blockfrost-js/blob/master/src/utils/helpers.ts#L144

The function accepts 4 parameters (naming borrowed from Python implementation):

• request_body: whole request's body in bytes (or stringified body, depending which will be easier for users in given language and its most popular web frameworks)
• signature_header: Blockfrost-Signature header that will be included in every webhook request
• secret: webhook auth token that is used to sign the request (user will find it in Blockfrost Dashboard)
• timestamp_tolerance_seconds: optional, default 600s. Time window for checking the validity of the signature. If the computed signature matches the signature received in the request, but the timestamp is too old, the signature is considered to be invalid.

If the signature is valid then the function returns True. Otherwise It throws SignatureVerificationError with various error messages (see reference implementations for more details). The error object has additional fields header and request_body for debugging purposes.

Use test vectors from reference implementation's fixtures in your own unit tests to verify the correctness of your implementation. https://github.com/blockfrost/blockfrost-python/blob/master/tests/test_helpers.py

Webhook Endpoint

The example of using webhooks should implement /webhook endpoint for processing events sent by Blockfrost Secure Webhooks. It has to showcase verifying the signature (described above), parsing the event payload (while printing basic information into the console) and return status code 200 on success. The web app should be exposed on port 6666.

For reference examples see https://blockfrost.dev/docs/start-building/webhooks/using-webhooks#process-a-webhook-request

[theeldermillenial]

Is this still ongoing? Will you accept Python examples? I'm considering building one with FastAPI.

[slowbackspace]

Hi @theeldermillenial! Thank you for you interest in helping us to improve the documentation.

Yes, we do accept new examples along with implementation of Signature Verification. However, we already have Python implementation for a verification of a webhook signature and basic examples of the usage using Flask framework: https://blockfrost.dev/docs/start-building/webhooks/webhooks-signatures#using-sdk https://blockfrost.dev/docs/start-building/webhooks/using-webhooks#process-a-webhook-request

I am not sure if changing the framework to FastAPI brings additional value to the developers as the Flask itself is not that important in these examples. But, I am not familiar with FastAPI, are there big enough differences that would justify adding another Python example? Alternatively, would you be interested in implementing these in any other language?

[theeldermillenial]

@slowbackspace I did see the Flask example. I think you're correct, I don't think changing the framework to FastAPI changes your code example that much. If you know how to use FastAPI, the Flask example is more than sufficient. I think maybe the one benefit to it would be construction of the pydantic class for handling the hook. I believe I have an open request on the docs repo to improve the openAPI schema, because if the schema is better then you can autogenerate pydantic classes for validating responses better.

As for another language, I don't know that it's worth my time. I was just curious since I'll be developing this anyway.