Webhooks

Give another service a URL to call, and turn each of its calls into an event that starts your workflows.

Many services announce what happens on their side by calling a URL you give them: a payment succeeded, a pull request was merged, a form was submitted. A webhook is that URL. Nelkap receives each call, turns it into an event in your project, and starts every workflow that listens for that event, with the call’s body as the payload.

You don’t write, host, or scale any code to receive the calls.

Create a webhook

1. Create the webhook

   Go to Webhooks in the console and create one. Choose its project and the event it emits, like checkout.completed.

2. Copy its URL

   Reveal the webhook’s URL and copy it. It looks like https://api.nelkap.com/webhooks/<secret>.

3. Give the URL to the other service

   Paste the URL in the other service’s webhook settings, as the address it calls.

4. Listen for the event

   Register a workflow that listens for the webhook’s event:

   nelkap/index.ts

   nelkap.registerWorkflows([
     {
       name: 'fulfillOrder',
       handler: fulfillOrder,
       events: ['checkout.completed'],
     },
   ]);
   

Each call now starts a run of fulfillOrder. Its payload is the call’s JSON body, exactly as the service sent it, so type it after the service’s own documentation:

nelkap/workflows/fulfill-order.ts

import { createShipment, sendConfirmation } from '../../orders';
import { nelkap } from '../client';

type Checkout = {
  id: string;
  customer_email: string;
};

export async function fulfillOrder(checkout: Checkout) {
  await nelkap.step.run('shipment', () =>
    createShipment(checkout.id),
  );

  await nelkap.step.run('confirmation', () =>
    sendConfirmation(checkout.customer_email),
  );
}

Test a webhook

Send a call yourself, with the body the service would send:

curl -X POST https://api.nelkap.com/webhooks/<secret> \
  -H 'Content-Type: application/json' \
  -d '{"id":"cs_42","customer_email":"[e-mail]"}'

The event shows on the Events page, with the runs it started.

Accepted requests

Each call must be a POST with a JSON body, up to your plan’s request size of 1 to 3 MB. Nelkap answers:

Status	When
200	The event was emitted, and the workflows that listen for it started their runs.
400	The body isn’t JSON, or it’s nested more than 64 levels deep.
402	The workspace is no longer active.
403	The call came from an IP address the webhook doesn’t allow.
404	No enabled webhook has this URL.
413	The body is larger than your plan allows.
429	Your workspace made more requests this second than your plan allows.

Most services call again later when they don’t get a 2xx answer.

A webhook emits its event without tags and without a wakeOn key, so it starts runs but doesn’t wake waiting ones. To wake a run from another service’s call, receive the call in your app and emit the event yourself.

Security

The secret in the URL is what proves a call is meant for your project. Treat the URL like a password:

• If it leaks, rotate the webhook’s secret. The old URL stops working at once, so paste the new one in the other service right after.
• To accept calls only from the service’s servers, set the webhook’s allowed IPs: up to 20 addresses or ranges, like 203.0.113.7 or 203.0.113.0/24, in IPv4 or IPv6.

Nelkap doesn’t check the signatures some services add to their calls. When you need that check, receive the call in a route of your app, check the signature there, then emit the event with nelkap.emit. The order fulfillment example does this for Stripe.

Disable a webhook

Disable a webhook to stop it for a while without losing its URL. While it’s disabled, its calls get a 404 and emit nothing. Enable it again, and the same URL works as before. You can also change the event a webhook emits, or its allowed IPs, at any time.

Webhook list

The Webhooks page of the console lists each webhook with its event, its project, its allowed IPs, its status, and the number of events it has emitted. The events themselves are listed with every other event, with the runs each one started. See Event history.

Permissions

Action	Role
See webhooks	Every member of the workspace
Create, change, disable a webhook, or reveal its URL	Member or above
Rotate a webhook’s secret	Admin or above

Your plan sets how many webhooks your workspace can have: 50, 100, or 500. See Limits.