Skip to main content

Webhook

This guide will help you understand how to leverage the Naas webhook job to run notebooks like APIs.

Deploying Your Notebook​

To deploy this notebook and generate a URL that triggers it, use the following command:

naas.webhook.add()

You can also deploy other notebooks by specifying the path to the notebook:

naas.webhook.add(path="path/to/my/awesome/notebook.ipynb")

Using Parameters with Your Webhook​

You can customize your webhook with the following parameters:

  • notif_down: Get an email if the notebook execution fails.
  • notif_up: Get an email when the notebook executes successfully.
  • next_url: Redirect users to a different URL after running the notebook.
  • inline: Receive the result directly in your web browser instead of as a download.
params = {"notif_down": "[email protected]", "notif_up": "[email protected]"}
naas.webhook.add(params=params)

Incorporating Dynamic Parameters​

When you access your notebook URL through a GET or POST request, you can pass parameters with the MIME types application/x-www-form-urlencoded or application/json. These parameters will be included in a new cell at the top of your notebook.

If you want these parameters to appear in a specific place, simply add a parameters tag to a cell, and the dynamic parameters will be inserted in a new cell next to it.

The screenshot below shows a notebook with predefined variables in the first cell and injected dynamic parameters in the second cell.

If you need to debug your webhook, you can do so by setting debug=True:

naas.webhook.add(debug=True)

Ways to Return Results from Your Notebook​

Running a notebook through the API allows for various types of results:

HTML​

Return an HTML payload. Remember to keep it simple!

naas.webhook.respond_html("<h1>Hello, world!</h1>")

JSON​

naas.webhook.respond_json({"foo": "bar"})

Image​

import requests
url = "https://picsum.photos/id/237/200/300"
naas.webhook.respond_image(requests.get(url, stream=True).content)

SVG​

# Jupyter logo in SVG format
jupyterlogo = '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Jupyter icon</title><path d="M7.157 22.201A1.784 1.799 0 0 1 5.374 24a1.784 1.799 0 0 1-1.784-1.799 1.784 1.799 0 0 1 1.784-1.799 1.784 1.799 0 0 1 1.783 1.799zM20.582 1.427a1.415 1.427 0 0 1-1.415 1.428 1.415 1.427 0 0 1-1.416-1.428A1.415 1.427 0 0 1 19.167 0a1.415 1.427 0 0 1 1.415 1.427zM4.992 3.336A1.047 1.056 0 0 1 3.946 4.39a1.047 1.056 0 0 1-1.047-1.055A1.047 1.056 0 0 1 3.946 2.28a1.047 1.056 0 0 1 1.046 1.056zm7.336 1.517c3.769 0 7.06 1.38 8.768 3.424a9.363 9.363 0 0 0-3.393-4.547 9.238 9.238 0 0 0-5.377-1.728A9.238 9.238 0 0 0 6.95 3.73a9.363 9.363 0 0 0-3.394 4.547c1.713-2.04 5.004-3.424 8.772-3.424zm.001 13.295c-3.768 0-7.06-1.381-8.768-3.425a9.363 9.363 0 0 0 3.394 4.547A9.238 9.238 0 0 0 12.33 21a9.238 9.238 0 0 0 5.377-1.729 9.363 9.363 0 0 0 3.393-4.547c-1.712 2.044-5.003 3.425-8.772 3.425Z"/></svg>'

naas.webhook.respond_svg(jupyterlogo)

Text​

# Example text
text = "Hello Naas friends, do you love markdown as much as we do?"

naas.webhook.respond_text(text)

Markdown​

# Example MD
markdown_text = "# Hello Naas friends<br /> Do you love markdown as much as we do?"

naas.webhook.respond_markdown(markdown_text)

CSV​

Please avoid large CSV files, as it can cause your notebook to crash. Instead, consider using the "File" option.

# Example Csv
csv_text = """
Sally Whittaker,2018,McCarren House,312,3.75
Belinda Jameson,2017,Cushing House,148,3.52
Jeff Smith,2018,Prescott House,17-D,3.20
Sandy Allen,2019,Oliver House,108,3.48
"""

naas.webhook.respond_csv(csv_text)

File​

This is intended for sending large files that are not embedded in the notebook:

naas.webhook.respond_file("test.csv")

Note: If your file is not generated by a notebook, remember to add it as a Dependency to avoid it being missing in the production folder.

Notebook​

Respond with the notebook output using:

naas.webhook.respond_notebook()

Retrieving URLs​

For Current File​

url = naas.webhook.find()

For Other Files​

url = naas.webhook.find(path="path/to/my/super/notebook.ipynb")

Listing Versions​

List all versions of a file in production:

For Current File​

naas.webhook.list()

For Other Files​

naas.webhook.list(path="path/to/my/super/notebook.ipynb")

Getting Files​

Retrieve a version of a file in production:

To Get the Last One​

naas.webhook.get()

With a File Path​

naas.webhook.get(path="path/to/my/super/notebook.ipynb")

With a History ID​

naas.webhook.get(histo="20201008101221879662")

Combined​

naas.webhook.get(path="path/to/my/super/notebook.ipynb", histo="20201008101221879662")

Clearing Files​

Remove previous versions of a file from production:

One​

naas.webhook.clear(histo="20201008101221879662")

Other Notebook​

naas.webhook.clear(path="path/to/my/super/notebook.ipynb", histo="20201008101221879662")

All​

naas.webhook.clear()

All for a Specific File Path​

naas.webhook.clear(path="path/to/my/super/notebook.ipynb")

Retrieving Output​

Get the output of the production file:

To Get the Last One​

naas.webhook.get_output()

With a File Path​

naas.webhook.get_output(path="path/to/my/super/notebook.ipynb")

Clearing Output​

Remove the previous output of a file from production:

One​

naas.webhook.clear_output()

Other Notebook​

naas.webhook.clear_output(path="path/to/my/super/notebook.ipynb")

Deleting Webhooks​

You can remove any scheduler capability like that, it takes optionally a path.

For Current Notebook​

naas.webhook.delete()

For Other File​

naas.webhook.delete(path="path/to/my/super/notebook.ipynb")

For Debugging​

naas.webhook.delete(debug=True)

Listing Webhooks​

Forgot how many Webhook notebooks you have?

naas.webhook.currents()

Raw Result​

naas.webhook.currents(raw=True)

This function lists all your current Webhook notebooks. If you need more detailed information, you can get the raw results by setting raw=True.

And that's it! You now have a comprehensive guide on how to use the naas.webhook module to run notebooks through URLs, handle different types of responses, manage your Webhook notebooks, and debug issues. Feel free to experiment with different parameters and options to best suit your project's needs. Remember, efficient data handling and clear communication are key to successful projects!