Webhooks

The Webhooks feature in Sheetrocks allows users to create custom server-side logic to handle incoming requests and trigger actions. Webhooks are essential for building real-time integrations with third-party services or automating workflows. Sheetrocks handles the webhook runtime and scaling, letting you focus solely on your business logic.

Getting Started

For first-time users, we recommend exploring our GitHub repository for starter templates and example code. The example form application demonstrates how to use webhooks to process form data and integrate it with your Sheetrocks workbook.

The webhook feature is designed to be straightforward. By focusing on JSON input/output, we make it easy to integrate with third-party services while avoiding the complexity of managing server infrastructure. Sheetrocks handles the runtime environment, so you only need to focus on writing your custom business logic.

How Webhooks Work

At its core, a webhook in Sheetrocks is a simple JavaScript file that is executed in a secure, serverless environment on our platform. It expects and processes JSON data and returns a JSON response.

1. Incoming Request: When a webhook is triggered, Sheetrocks processes the incoming request, converts it to JSON, and stores it in a special file called request.json. This file contains all the data sent from the webhook trigger.
‍
2. Custom Logic Execution: Your webhook JavaScript file reads the request.json, processes the data as needed, and generates a response object.
‍
3. Outgoing Response: The response from your logic is written to a response.json file. This file contains the data that will be sent back to the user or application that triggered the webhook.

An Example

Below is an example of a minimal webhook to accept a form request, append that information to a sheet, and then respond.

import fs from 'fs';
import axios from 'axios';

axios.defaults.headers.common['Authorization'] = `Bearer
${process.env.API_TOKEN}`;
axios.defaults.headers.common['Content-Type'] = 'application/json';

// A "Hello World" webhook.
// Takes a request, appends it to a sheet, return a success message.

async function writeToSheet() {
// The request data comes in a special request.json file.
const request = JSON.parse(fs.readFileSync('request.json', 'utf8'));
// You can use the environment parameters to perform authenticated operations on the workbook.
const sheetId = (await axios.get(`${process.env.BASE_URL}/api/v1/workbook/${process.env.WORKBOOK_ID}`)).data.Sheets[0].ID;
const url = `${process.env.BASE_URL}/api/v1/workbook/${process.env.WORKBOOK_ID}/sheet/${sheetId}/append`;
await axios.post(url, { Cells: [[`${request.body.name}`, `${request.body.email}`]] });

// When you're done, write a response.json file with the response. fs.writeFileSync('response.json', JSON.stringify({ success: true }))}

writeToSheet();

Supported Data and Formats

Sheetrocks webhooks are optimized to accept and return JSON data. This makes them compatible with most APIs and services that communicate using JSON.

Data Received: Sheetrocks webhooks can receive any JSON-formatted data. Common use cases include form submissions, event notifications, or API calls from external services like Stripe, Slack, or Typeform.
Data Returned: The response generated by your webhook must also be in JSON format. This can include processed data, status messages, or anything else needed for the triggering service.

Setting Up a Webhook

At its core, a webhook in Sheetrocks is a simple JavaScript file that is executed in a secure, serverless environment on our platform. It expects and processes JSON data and returns a JSON response.

1. Create Your Webhook: Write your custom logic in a JavaScript file. This file should contain a main function that reads the incoming data from request.json, processes it, and writes a response to response.json.
‍
2. Deploy the Webhook: Push your JavaScript file to Sheetrocks via the webhook interface. Sheetrocks handles the runtime, scaling, and security of the webhook so you don’t have to manage servers or infrastructure.
‍
3. Trigger the Webhook: Once deployed, the webhook can be triggered by external services or automation tools. When a request is made, Sheetrocks executes your JavaScript code and returns a JSON response to the requestor.

Benefits of Sheetrocks Webhooks

Serverless Architecture: Sheetrocks webhooks run on a fully managed, serverless infrastructure. You don’t need to provision or manage servers, making it a hassle-free way to deploy custom logic.
Secure and Scalable: Each webhook runs in a secure, isolated environment with user-specific authentication. Our platform handles scaling to accommodate the number of incoming requests.
API-First Approach: Webhooks in Sheetrocks allow you to seamlessly interact with your workbook’s data, providing a flexible way to integrate Sheetrocks with third-party services and APIs.

Debugging and Error Handling

Sheetrocks provides a detailed logging system for webhooks. You can view execution logs for each request, which include:

Run Time: The total time taken to execute the webhook.
Console Output: Any console.log statements within your JavaScript file will appear in the logs, making it easy to debug issues.
Error Messages: If the webhook fails, error messages will be logged for further inspection.

These logs are available directly within the webhook interface, making it easy to diagnose and fix any issues.

Common Integrations

Sheetrocks webhooks integrate easily with external services and APIs. Some common integrations include:

Stripe: Use webhooks to handle payment events, such as receiving notifications when a customer completes a purchase.
Slack: Integrate Slack to send real-time updates from your Sheetrocks workbook to a Slack channel.
QuickBooks: Automatically update financial records in QuickBooks based on data in your workbook.

⚠️ Security Considerations ⚠️

‍
Private by Default: All webhook data is processed in a secure, server-side environment. Webhooks are authenticated per user, ensuring that data remains protected.

‍Access Control: Be mindful of who has access to your webhook endpoints, especially if they handle sensitive data.

Error Handling: Sheetrocks securely handles failed webhook deliveries and logs errors for troubleshooting.

Note: One aspect that might be unconventional is how Sheetrocks handles request and response data through files (request.json and response.json). This file-based approach ensures strict security boundaries but can feel unfamiliar to developers used to working with objects in memory. Once understood, however, it offers a secure and manageable way to process requests.