Working with webhooks
Build a webhook handler that receives record changes from Tape, verify it, and test it on your own machine.
A webhook sends a POST request to your URL whenever something changes in a database app. The Webhook reference lists every endpoint and event type.
Before you begin
You need:
- A personal access token with the capabilities Manage webhooks (
webhooks:manage) and Read records (records:read). Add Edit records (records:edit) if your handler changes records. - The ID of the app you want to watch. Open one of its records in Tape, select •••, then select Developer, and copy the App ID. A record you read with the API also returns it as
app_id. - The Admin role in the app's workspace.
- Node.js 18 or later, and the Express package (
npm install express).
Store the token in an environment variable:
export TAPE_TOKEN=tape_pat_0a1b2c3d...
How a webhook becomes active
- You create a webhook with a URL and an event
type. It starts asinactive. - Tape sends
hook.verifywith acodeto your URL right away. - Your handler sends the code back to Tape. The webhook becomes
active. - From then on, Tape sends one POST request per event to your URL.
Every event carries IDs only, for example record_id and revision_id. Read the record with your token to get its values.
Step 1: Write the handler
Create server.js:
const express = require('express');
const TAPE_API = 'https://api.tapeapp.com';
const headers = {
Authorization: `Bearer ${process.env.TAPE_TOKEN}`,
'Content-Type': 'application/json',
};
const app = express();
app.use(express.json());
app.post('/tape-webhook', async (req, res) => {
// Answer first. Tape waits 5 seconds at most.
res.sendStatus(200);
const { type, hook_id, code, record_id } = req.body;
if (type === 'hook.verify') {
await fetch(`${TAPE_API}/v1/hook/${hook_id}/verify/validate`, {
method: 'POST',
headers,
body: JSON.stringify({ code }),
});
console.log(`Webhook ${hook_id} verified`);
return;
}
if (type === 'record.update') {
const record = await fetch(`${TAPE_API}/v1/record/${record_id}`, { headers }).then((r) => r.json());
console.log(`Record ${record_id} updated: ${record.title}`);
}
});
app.listen(3000, () => console.log('Listening on port 3000'));
Start it:
node server.js
Key points
res.sendStatus(200)comes first. Slow work after the response doesn't count against the time limit.- The handler validates the code itself, so verification needs no manual step.
- Tape doesn't sign webhook requests, so the handler reads the record with your token. Don't trust the payload for anything but IDs.
Step 2: Make the handler reachable
Tape sends webhooks only to ports 80 and 443. A server on localhost:3000 isn't reachable from the internet.
To test on your machine, start a tunnel such as ngrok or Cloudflare Tunnel. It forwards a public HTTPS URL on port 443 to your local port:
ngrok http 3000
Copy the HTTPS URL it prints, for example https://acme-test.ngrok.app. Your webhook URL is that address plus /tape-webhook.
In production, run the handler behind HTTPS on port 443. Tape sends the same payload over HTTP, but HTTPS keeps it private.
Step 3: Create the webhook
Keep the handler and the tunnel running. Make a POST request with the URL and the event type. Replace 1 in the path with your app ID:
curl -X POST https://api.tapeapp.com/v1/hook/app/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"type": "record.update",
"url": "https://acme-test.ngrok.app/tape-webhook"
}'
{
"hook_id": 7,
"app_id": 1,
"status": "inactive",
"num_failed_executions": 0,
"type": "record.update",
"url": "https://acme-test.ngrok.app/tape-webhook"
}
One webhook receives one event type. To receive created and updated records, create two webhooks with the same URL.
Step 4: Verify the webhook
Your handler received hook.verify right after Step 3 and logs Webhook 7 verified. Check the status, again with your app ID in place of 1:
curl https://api.tapeapp.com/v1/hook/app/1 \
-H "Authorization: Bearer $TAPE_TOKEN"
The webhook now shows "status": "active".
Check that the tunnel runs, that the URL ends with /tape-webhook, and that your handler answers within 5 seconds. Then request the verification again with the hook_id from the response:
curl -X POST https://api.tapeapp.com/v1/hook/7/verify/request \
-H "Authorization: Bearer $TAPE_TOKEN"
Step 5: Send a test event
Change any field of a record in that database app, in Tape or with Update a record. Tape sends this body to your handler:
{
"hook_id": 7,
"record_id": 100,
"revision_id": 1,
"type": "record.update"
}
Your handler logs the update:
Record 100 updated: Andrea Lim
Avoid endless loops
A handler that updates a record in the same app starts a new record.update event. That event calls the handler again, and the loop never ends.
Add hook=false to every request your handler sends to change records. In this example, status is the slug of a field in the app:
await fetch(`${TAPE_API}/v1/record/${record_id}?hook=false&silent=true`, {
method: 'PUT',
headers,
body: JSON.stringify({ fields: { status: 'Reviewed' } }),
});
hook=falseruns no webhooks for this change. It works on create, update, delete, restore and the batch endpoints.silent=truesends no notifications for this change.workflow=falsealso skips automations, if one of them reacts to the same field.
Handle failures
Respond to every webhook request with a 2xx status code within 5 seconds:
- After more than 50 failed requests in a row, the webhook becomes inactive. Request the verification again to activate it.
- Tape retries a request briefly after a timeout, a network error, a
429or a5xxresponse. Other status codes fail at once. - Tape doesn't follow redirects. Use the final URL, including
https. - Send an empty body or a short one, such as
OK. A long body, such as an HTML page, counts as a failed request. - The same event can arrive more than once. Use
record_idandrevision_idto skip events you already handled.
Tape sends at most 100 webhook requests per minute per app.