Webhooks

Webhooks allow external systems to trigger workflows in Nembl and receive notifications when events occur. Nembl supports both inbound webhooks (external systems calling Nembl) and outbound webhooks (Nembl calling external systems).

Inbound Webhooks

Inbound webhooks let external systems trigger Nembl workflows by sending HTTP requests to a unique webhook URL.

Creating an Inbound Webhook

1. Navigate to Settings > Developer > Webhooks.
2. Click Create Webhook.
3. Configure the webhook:
   • Name -- descriptive label (e.g., "GitHub Push Events", "Stripe Payment Webhook").
   • Target workflow -- the workflow to trigger when the webhook is called.
   • Target offering -- optionally map the webhook to a specific service offering, creating a request automatically.
4. Click Create.
5. Copy the generated webhook URL:

https://api.nembl.com/v1/webhooks/inbound/whk_abc123xyz

Calling the Webhook

Send a POST request to the webhook URL with a JSON payload:

curl -X POST https://api.nembl.com/v1/webhooks/inbound/whk_abc123xyz \
  -H "Content-Type: application/json" \
  -H "x-webhook-signature: sha256=abc123..." \
  -d '{
    "event": "deployment.completed",
    "environment": "production",
    "version": "v2.1.0",
    "status": "success"
  }'

Payload Format

Nembl accepts any valid JSON payload. The entire payload is passed to the workflow as input data, accessible via workflow variables:

{{ webhook.body.event }}          → "deployment.completed"
{{ webhook.body.environment }}    → "production"
{{ webhook.body.version }}        → "v2.1.0"

Additional metadata is available:

{{ webhook.headers.content-type }}  → "application/json"
{{ webhook.method }}                 → "POST"
{{ webhook.receivedAt }}             → "2026-04-01T10:30:00Z"

Webhook Response

Nembl responds immediately with a 202 Accepted status, indicating the webhook was received and the workflow will be triggered asynchronously:

{
  "status": "accepted",
  "webhookId": "whk_abc123xyz",
  "executionId": "exec_def456"
}

The executionId can be used to track the workflow execution via the API.

Signature Verification

Protect your webhook endpoints from unauthorized calls by enabling signature verification.

How It Works

1. When creating a webhook, Nembl generates a signing secret.
2. Copy and store the signing secret securely.
3. When calling the webhook, compute an HMAC-SHA256 signature of the request body using the signing secret and include it in the x-webhook-signature header.
4. Nembl verifies the signature before processing the webhook.

Computing the Signature

const crypto = require('crypto');
 
const secret = 'whsec_your_signing_secret';
const body = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');
 
// Send as header: x-webhook-signature: sha256=<signature>

import hmac
import hashlib
 
secret = b'whsec_your_signing_secret'
body = json.dumps(payload).encode()
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
 
# Send as header: x-webhook-signature: sha256=<signature>

Disabling Verification

For development and testing, signature verification can be disabled on individual webhooks. This is not recommended for production use.

Retry Behavior

When Nembl calls outbound webhooks (notifications to external systems), it retries on failure.

Retry Schedule

After 5 failed retries, the webhook delivery is marked as failed and logged in the webhook delivery history.

What Counts as a Failure

• HTTP status codes 4xx (except 410 Gone, which disables the webhook) and 5xx.
• Connection timeouts (30 seconds).
• DNS resolution failures.

A 2xx response from your server is considered successful delivery.

Outbound Webhooks (Event Notifications)

Configure Nembl to notify external systems when events occur.

Subscribing to Events

1. Navigate to Settings > Developer > Webhooks > Outbound.
2. Click Create Subscription.
3. Configure:
   • URL -- the endpoint Nembl will POST to.
   • Events -- select which events to subscribe to:

4. Click Save.

Event Payload Format

{
  "event": "request.created",
  "timestamp": "2026-04-01T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "serviceId": "svc_xyz789",
    "title": "New laptop request",
    "status": "PENDING",
    "priority": "MEDIUM",
    "createdBy": "user_def456"
  }
}

Webhook Delivery History

View the delivery history for any webhook from Settings > Developer > Webhooks:

• Delivery timestamp
• HTTP status code returned
• Response body (first 1 KB)
• Retry count
• Success or failure status

Use the delivery history to debug integration issues and verify that events are being received.

Best Practices

• Always verify signatures in production. Signature verification prevents unauthorized parties from triggering your workflows.
• Respond quickly. Return a 2xx response as fast as possible. Do heavy processing asynchronously after acknowledging receipt.
• Handle duplicates. Retries may deliver the same event twice. Use the executionId or event ID for idempotent processing.
• Monitor delivery failures. Check the delivery history regularly and fix failing endpoints to avoid missing events.
• Use HTTPS endpoints. Nembl only delivers outbound webhooks to HTTPS URLs.