# Workato Webhooks

Workato is an automation platform with no native outbound webhooks. A recipe pushes data to
your app with the HTTP connector's **Send request via HTTP** action, using an HTTP connection set to **Basic**
authentication. Workato does not sign these requests, so your endpoint authenticates them
with the Basic auth username and password and routes them by an `event` field you put in the
body.

## When to Use This Skill

* How do I receive webhooks from a Workato recipe?
* How do I secure an endpoint that Workato's HTTP connector calls?
* How do I verify the `Authorization: Basic` header Workato sends?
* Does Workato sign webhook requests? (No: static Basic auth credential)
* Why does my Workato HTTP action get a 401 from my webhook endpoint?

## Verification (core)

Parse `Authorization: Basic base64(username:password)` (scheme is case-insensitive), split on
the **first** colon, and compare the username and the password each in constant time. Evaluate
both before deciding:

```javascript
const crypto = require('crypto');

function safeEqual(a, b) {
  const ba = Buffer.from(String(a), 'utf8');
  const bb = Buffer.from(String(b), 'utf8');
  if (ba.length !== bb.length) return false;       // timingSafeEqual needs equal lengths
  return crypto.timingSafeEqual(ba, bb);
}

function verifyWorkatoRequest(headers, user, password) {
  if (!user || !password) return false;            // never accept when unconfigured
  const m = (headers['authorization'] || '').match(/^Basic\s+([A-Za-z0-9+/]+={0,2})\s*$/i);
  if (!m) return false;
  const decoded = Buffer.from(m[1].trim(), 'base64').toString('utf8');
  const sep = decoded.indexOf(':');                // password may contain ':'
  if (sep === -1) return false;
  const userOk = safeEqual(decoded.slice(0, sep), user);
  const passwordOk = safeEqual(decoded.slice(sep + 1), password);
  return userOk && passwordOk;                     // no short-circuit above
}

```

Return `401` when this fails, `400` for a non-empty body that isn't a JSON object, and `200`
once handled. Authenticate before parsing the body, and read it raw
(`express.raw({ type: '*/*' })`) so any content type works. Python and Next.js equivalents are
in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/workato-webhooks/references/verification.md).

**A static shared credential authenticates the sender, not the body, and gives no replay
protection** (no signature, no timestamp). Use HTTPS only, and rotate the password if it leaks.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/workato-webhooks/examples/express/),
> [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/workato-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/workato-webhooks/examples/fastapi/).

## HTTP Methods and Empty Bodies

The method is whatever the recipe's HTTP action is set to, so the examples accept `POST`,
`PUT`, `PATCH`, `GET` and `DELETE` on the route and treat an empty body (typical for `GET`) as
`{}`.

## Event Types

Workato defines no webhook event types; the payload is whatever the recipe sends. Send
`{"event": "...", "data": {...}}` and dispatch on `event`. The examples use these names, which
are a convention, not Workato values:

| Event | Sent When |
| --- | --- |
| `order.created` | A recipe sees a new order |
| `record.updated` | A recipe syncs a changed record |
| `recipe.failed` | An error-handling step reports a failure |

## Environment Variables

```bash
WORKATO_WEBHOOK_USERNAME=workato                              # "Basic auth user"
WORKATO_WEBHOOK_PASSWORD=replace-with-a-long-random-password  # "Basic auth password"

```

## Local Development

Workato can't reach `localhost`. Tunnel with the Hookdeck CLI (no account required):

```bash
npx hookdeck-cli listen 3000 workato --path /webhooks/workato

```

Use the printed URL as the HTTP connection's **Base URL**.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/workato-webhooks/references/overview.md) - How Workato sends requests, suggested payload shape, example events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/workato-webhooks/references/setup.md) - Configure the HTTP connection and recipe action
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/workato-webhooks/references/verification.md) - Basic auth check in Node, Python and Next.js, gotchas, debugging 401s
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/workato-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests