Ulabase

Build

Webhooks

Call an HTTP endpoint or send an email when a request to your service matches a condition you write, for example a Slack message for every new order.

A webhook is a call your service makes to another system when something happens. On Ulabase a webhook calls an HTTP endpoint or sends an email when a request to your service matches a condition you write.

Use it to post a message on Slack for every new order, or to tell your own backend that a document was written.

What you get:

  • No code to deploy. You set up a webhook in the console.

  • The message the other system expects. A template shapes what is sent, so it fits Slack, Mailjet or your backend.

The Webhooks page: the feature enabled and three webhooks

How it works

For every request your service handles, each webhook evaluates its condition against the request and its response. When the condition matches, the webhook sends an HTTP POST or an email.

Webhooks run after the response has gone back to the client, so they never slow down or break a request. The webhooks of one request run one after another, and a failure in one does not stop the others.

Turn it on

  1. Open Service → Webhooks.

  2. Click Enable webhooks.

The badge beside the title says whether the feature is ENABLED or DISABLED. Disable stops every webhook and keeps their configuration.

Two kinds of webhook

HTTP webhooks

Send an HTTP POST to a public URL when the condition matches.

Field Required Description

name

Yes

A name you recognise, such as "New User Slack Alert".

condition

Yes

Predicate expression. See Conditions below.

url

Yes

Destination URL, https only, on a public host: an address of a private network, of the local machine or of a cloud metadata service is refused when you save it and before every call. Use https://httpbin.org/post for testing.

timeout_ms

No

How long the call waits for the answer, in milliseconds, from 1000 up to what the plan allows: 30000 on Free, 60000 on Starter and Pro. Default: 5000.

headers

No

JSON object of headers sent with the request, for example for authentication.

transform.enabled

No

Boolean. When true, the Mustache template below shapes the request body.

transform.template

No

Mustache template for the request body. See Shape the payload.

Email webhooks

Send an email when the condition matches, through the service’s mail server.

Note
These count against your service’s daily email allowance. A webhook with several recipients takes them all or none: five addresses with three left sends nothing. With your own mail server no limit applies.

What the email says, and who gets it, depends on the server it leaves from (Email):

  • From our address, noreply@ulabase.app: the subject and the body are ours. The subject names your app, the collection and the event (Acme: orders, created); the body lists the top-level fields of the document that triggered the webhook, scalars only, cut to 200 characters, with your brand on top. The recipients in email.to and email.cc are resolved as usual, Mustache included, and then only the members of your organization and the users of your app with a verified address are kept: the others are refused, and the webhook’s log lists them with the reason. email.subject, email.bodyTemplate and email.htmlTemplate are ignored.

  • From your own mail server, set on the Email page: your subject, your template, any recipient. The email closes with a block you cannot remove, saying it was sent by your app through Ulabase, with a link to report it.

Field Required Description

name

Yes

A name you recognise.

condition

Yes

Predicate expression.

email.to

Yes

Array of recipient email addresses.

email.cc

No

Array of CC email addresses.

email.subject

With your own server

Subject line. Supports Mustache variables. Ignored from our address.

email.bodyType

With your own server

"json" or "html".

email.bodyTemplate

With json

JSON template with Mustache variables. The result is sent as an HTML table.

email.htmlTemplate

With html

HTML template with Mustache variables. {{field}} writes the value as text, so a field your users write cannot add tags or links to the email; {{{field}}} writes it as it is, for a field that holds HTML you trust.

How many, how fast

Each plan allows so many webhooks on a service (5 on Free, 10 on Starter, 25 on Pro) and so many calls in flight at a time (4, 8, 16). A webhook beyond the first number is refused where you create it. A call beyond the second is skipped, the log says so, and your own request goes through regardless: a webhook never slows down or fails the request that fired it. The response a webhook returns is kept in the log up to 4 KB.

A call waits 5 seconds for the answer, or the timeout_ms you set, up to 30 seconds on Free and 60 on Starter and Pro. A timeout_ms over the plan’s is refused where you save it.

Manage webhooks

The list

The page lists your webhooks in a table you can search by name, URL or condition. Click a row to see its details and its buttons.

Create one

  1. Click Add webhook.

  2. Under Webhook type, choose HTTP Request or Email.

  3. Fill in the fields.

  4. Click Add webhook.

Edit one

Open the row and click Edit. The form opens with the current values. Click Save when done.

Delete one

Open the row and click Delete. The webhook is removed after you confirm.

Do it from the command line

You can keep your webhooks in git and apply them with ulabase setup. The steps install the webhook-integration feature and add a webhook that posts to Slack on every new order. Each webhook has the fields above and an id you choose:

import { defineSetup, step, fromEnv } from '@ulabase/cli';

// a webhook that calls Slack on every new order; the Slack URL is a secret from the environment
const newOrder = {
  id: 'new-order',
  name: 'New order Slack alert',
  condition: "path('/orders') and method('POST')",
  url: fromEnv('SLACK_WEBHOOK_URL'),
  timeout_ms: 5000,
};

export default defineSetup('Webhooks', [
  // step 1: install the webhook feature, if it is not installed yet
  step('webhooks feature installed', {
    check: ({ admin, srvId }) => admin.isFeatureInstalled(srvId, 'webhook-integration'),
    apply: ({ admin, srvId }) => admin.installFeature(srvId, 'webhook-integration'),
  }),

  // step 2: save the webhook, unless one with this id and condition is already saved
  step('new order alert configured', {
    async check({ admin, srvId }) {
      const c = await admin.getFeatureConfig(srvId, 'webhook-integration');
      const hooks = (c.webhooks ?? []) as Array<{ id: string; condition: string }>;
      return hooks.some(h => h.id === newOrder.id && h.condition === newOrder.condition);
    },
    async apply({ admin, srvId }) {
      const current = await admin.getFeatureConfig(srvId, 'webhook-integration');
      // keep the other webhooks, such as those added from the console, and replace this one
      const others = ((current.webhooks ?? []) as Array<{ id: string }>).filter(h => h.id !== newOrder.id);
      await admin.updateFeatureConfig(srvId, 'webhook-integration', { ...current, webhooks: [...others, newOrder] });
    },
  }),
]);

The step replaces only the webhook with its id, so the webhooks added from the console stay.

For an email webhook, add "type": "email" and the fields of the email webhooks above. Without type, a webhook is HTTP.

Conditions

The condition field uses the Undertow predicate language, the same as permission rules. It is evaluated against the incoming request and its response.

Paths

path('/users')                        # exact path match
path-prefix('/orders')                # any path starting with /orders
path-template('/users/{id}')          # parameterised path
path-suffix('.csv')                   # path ending with .csv

Methods

method('POST')
method('PUT') or method('PATCH')

Combining them

path('/users') and method('POST')
path-prefix('/orders') and (method('POST') or method('PUT'))
path-template('/users/{id}') and method('DELETE')
not method('GET')

Common conditions

Goal Condition

Fire when a new user is created

path('/users') and method('POST')

Fire on any write to /orders

path-prefix('/orders') and (method('POST') or method('PUT') or method('PATCH'))

Fire when a specific resource is deleted

path-template('/products/{id}') and method('DELETE')

Tip
Use Recording to see the real request paths before you write a condition, so it matches your actual traffic.

Shape the payload

By default, the HTTP request body is a standard JSON payload that describes the event. Turn on transformation when the target expects its own format, such as Slack blocks or Mailjet’s API schema.

Transformations use Mustache templates with {{variable}} syntax. A webhook always sends a POST with Content-Type: application/json, so the template is a JSON object; the console refuses to save one that is not.

Variables

Variable Description

{{service.id}}

Identifier of the Ulabase service.

{{timestamp}}

ISO 8601 timestamp of the event.

{{request.method}}

HTTP method of the triggering request (e.g. POST).

{{request.path}}

Path of the triggering request (e.g. /users).

{{request.query}}

Query string of the triggering request.

{{request.body.fieldName}}

Any field from the request body. Use dot notation for nested fields.

{{request.headers.Header-Name}}

Any header from the incoming request.

{{response.statusCode}}

HTTP status code of the response.

{{response.body.fieldName}}

Any field from the response body.

{{response.headers.Header-Name}}

Any header from the response.

How values are written

A text value goes into the template as JSON text. A double quote, a backslash or a new line in a document field stays part of the value, so a field written by your users cannot break the payload or add fields to it. Write the variable between quotes, as in "{{request.body.message}}".

A whole object or array goes into the template as JSON. Write it without quotes, as in { "original": {{request.body}} }.

Numbers and booleans go in as they are.

Example: Slack Block Kit

{
  "text": "New event on {{service.id}}",
  "blocks": [{
    "type": "section",
    "text": {
      "type": "mrkdwn",
      "text": "*{{request.method}}* on `{{request.path}}`\nStatus: {{response.statusCode}}"
    }
  }, {
    "type": "context",
    "elements": [{
      "type": "mrkdwn",
      "text": "{{timestamp}}"
    }]
  }]
}

Example: Mailjet Send API

{
  "Messages": [{
    "From": { "Email": "noreply@yourdomain.com", "Name": "Your App" },
    "To": [{ "Email": "{{request.body.email}}", "Name": "{{request.body.name}}" }],
    "Subject": "Welcome!",
    "HTMLPart": "<h1>Hi {{request.body.name}}!</h1><p>Welcome to our service.</p>"
  }]
}

Under the template, Preview transformation renders it on sample JSON as you type. Paste the sample yourself, or click Load from logs to use a request the webhook recorded. Email webhooks have the same preview for the subject and the body.

Recording

A webhook keeps logs only while it is recording. Open its row and click Record (60s): for the next 60 seconds, every request the service receives is logged with what this webhook did, whether the condition matched or not. Stop recording ends it early.

Use it to:

  • see the exact field names in real request bodies before you write a template;

  • check that your condition matches the paths and methods your clients actually use.

Execution logs

Open the row and click View logs to see what was recorded. Each entry shows:

  • Timestamp

  • Status: success, failed or skipped

  • Duration in milliseconds

  • A summary of the outgoing request and the response

Click an entry to see the details:

Section What you see

Summary

Status and duration.

Incoming request

Method and path of the request that triggered the webhook.

Condition

The expression, and whether it matched.

Transformation

The input data and the rendered output, when transformation is on.

Outgoing request

The HTTP request sent to the target URL.

Response

Status code, headers and body received from the target.

The buttons All, Success, Failed and Skipped filter the list. The refresh icon reloads it, and Load more shows older entries. Logs are deleted after 30 days.

Testing

To test a webhook end to end, click Record (60s), send a request that matches the condition, and open View logs. During development, use https://httpbin.org/post as the target URL: it echoes back the payload it received, so you see what your service sends.

Tutorials

Slack notifications

Send a Slack message whenever a new user registers.

Step 1: Create a Slack incoming webhook

  1. Go to https://api.slack.com/messaging/webhooks.

  2. Click Create New App → From scratch, name the app, and select your workspace.

  3. Open Incoming Webhooks, switch it ON, and click Add New Webhook to Workspace.

  4. Select the target channel and copy the webhook URL.

Step 2: Configure it in Ulabase

Open Service → Webhooks and click Add webhook (type HTTP Request):

Field Value

Name

New User Slack Notification

URL

(your Slack webhook URL)

Condition

path('/users') and method('POST')

Timeout

5000

Transform

Enabled

Transformation template:

{
  "text": "New User Registered",
  "blocks": [{
    "type": "header",
    "text": { "type": "plain_text", "text": ":tada: New User Registered" }
  }, {
    "type": "section",
    "fields": [
      { "type": "mrkdwn", "text": "*Name:*\n{{request.body.name}}" },
      { "type": "mrkdwn", "text": "*Email:*\n{{request.body.email}}" }
    ]
  }, {
    "type": "context",
    "elements": [{ "type": "mrkdwn", "text": "Service: {{service.id}} | {{timestamp}}" }]
  }]
}

Step 3: Test with a real request

Click Record (60s) on the webhook, then send:

curl -X POST "https://c0ffee.ulabase.app/users" \
  -H "Authorization: Basic $(echo -n alice:secret | base64)" \
  -H "Content-Type: application/json" \
  -d '{"_id": "jane", "password": "s3cr3t", "roles": ["user"], "name": "Jane Smith", "email": "jane@example.com"}'

The message appears in Slack, and the entry under View logs.

More Slack templates

Order notification
{
  "text": "New Order",
  "blocks": [{
    "type": "section",
    "text": {
      "type": "mrkdwn",
      "text": ":shopping_cart: *Order #{{response.body._id}}*\nCustomer: {{request.body.customerName}}\nTotal: ${{request.body.total}}"
    }
  }]
}
5xx error alert
{
  "text": "API Error",
  "blocks": [{
    "type": "section",
    "text": {
      "type": "mrkdwn",
      "text": ":warning: *{{response.statusCode}}* on `{{request.method}} {{request.path}}`"
    }
  }]
}

Condition: method('POST') or method('PUT') or method('PATCH')


Email via Mailjet

Send a welcome email when a user registers.

Step 1: Set up Mailjet

  1. Sign up at https://www.mailjet.com.

  2. Go to Account Settings → API Key Management and copy your API Key and Secret Key.

  3. Go to Sender Addresses and verify your sending email address.

  4. Base64-encode your credentials:

    echo -n "YOUR_API_KEY:YOUR_SECRET_KEY" | base64

Step 2: Configure it in Ulabase

Field Value

Name

Welcome Email via Mailjet

URL

https://api.mailjet.com/v3.1/send

Condition

path('/users') and method('POST')

Timeout

10000

Headers

{ "Authorization": "Basic <base64_credentials>", "Content-Type": "application/json" }

Transform

Enabled

Transformation template:

{
  "Messages": [{
    "From": { "Email": "noreply@yourdomain.com", "Name": "Your App" },
    "To": [{ "Email": "{{request.body.email}}", "Name": "{{request.body.name}}" }],
    "Subject": "Welcome to Our Service!",
    "TextPart": "Hi {{request.body.name}},\n\nWelcome aboard!\n\nBest regards,\nThe Team",
    "HTMLPart": "<h1>Welcome {{request.body.name}}!</h1><p>We're glad to have you.</p>"
  }]
}

More Mailjet templates

Order confirmation
{
  "Messages": [{
    "From": { "Email": "orders@yourdomain.com", "Name": "Your Store" },
    "To": [{ "Email": "{{request.body.customerEmail}}", "Name": "{{request.body.customerName}}" }],
    "Subject": "Order Confirmation #{{response.body._id}}",
    "HTMLPart": "<h1>Thank you!</h1><p>Order #{{response.body._id}} — Total: ${{request.body.total}}</p>"
  }]
}

Email via SendGrid

Field Value

URL

https://api.sendgrid.com/v3/mail/send

Headers

{ "Authorization": "Bearer YOUR_SENDGRID_API_KEY", "Content-Type": "application/json" }

Transformation template:

{
  "personalizations": [{ "to": [{ "email": "{{request.body.email}}", "name": "{{request.body.name}}" }] }],
  "from": { "email": "noreply@yourdomain.com", "name": "Your App" },
  "subject": "Welcome!",
  "content": [{ "type": "text/html", "value": "<h1>Welcome {{request.body.name}}!</h1>" }]
}

Other targets

  • Discord: create an incoming webhook in the channel settings, and send a Slack-like payload.

  • Microsoft Teams: create an incoming webhook connector, and use the MessageCard JSON format.

  • Your own API: read the target’s API documentation, write a matching template, and test it with https://httpbin.org/post first.

Good practice

  • Write specific conditions, so a webhook does not fire on every request.

  • Record and check the logs before you rely on a webhook.

  • Set realistic timeouts: 5 to 10 seconds covers most external APIs.

  • Use HTTPS target URLs.

  • Send only the fields the target needs.

  • Several webhooks can share a condition. They all fire, one after another, and a failure in one does not affect the others.

Troubleshooting

Symptom Action

Webhook never triggers

Record, and compare the real request paths with your condition.

Status always skipped

The condition does not match. Check the path, method and response code against real traffic.

Target returns 401

Check that headers carries the right credentials for the target API.

Target returns 400

Open the log entry and look at Transformation. The rendered output must match what the target API expects.

Emails not delivered

Check that the sender address is verified with Mailjet or SendGrid, check spam folders, and look at the provider’s delivery dashboard.

Slack rejects the payload

Check the Block Kit JSON at https://app.slack.com/block-kit-builder.

Timeout errors

Increase timeout_ms, or check that the target answers promptly.