Webhooks & Automations

Webhooks allow you to build custom integrations and automations around define.wtf. Subscribe to real-time events when acronyms are created, edited, voted on, or deleted, and trigger custom workflows in external systems.

What are Webhooks?

Webhooks are HTTP callbacks that define.wtf sends to your system whenever something happens. Instead of polling define.wtf for changes, define.wtf pushes notifications to you in real-time.

How it works:

1. You register a webhook URL (your endpoint) in define.wtf
2. Something happens in define.wtf (e.g., new definition created)
3. define.wtf sends an HTTP POST to your webhook URL with event details
4. Your system receives the event and responds with a 2xx status code
5. You process the event (create Slack message, update database, trigger action, etc.)

Example flow:

New definition created in define.wtf
           ↓
define.wtf fires webhook
           ↓
POST https://example.com/webhooks/define
{
  "event": "definition.created",
  "definition": {...},
  "timestamp": "2024-03-28T10:30:00Z"
}
           ↓
Your system receives event
           ↓
Your system creates Slack message: "#announcements: New acronym: OKR"

Supported Events

define.wtf fires webhooks for all mutations (create, update, delete operations):

Acronym Events

Definition Events

Vote Events

Category Events

Collection Events

Tag Events

User Events

Webhook Payload Format

All webhooks use JSON format with this structure:

{
  "event": "definition.created",
  "timestamp": "2024-03-28T10:30:00Z",
  "tenantId": "tenant-abc123",
  "userId": "user-xyz789",
  "data": {
    "definition": {
      "id": "def-123",
      "text": "A goal-setting framework...",
      "acronymId": "acr-456",
      "author": "jane.doe@acme.com",
      "votes": 5,
      "createdAt": "2024-03-28T10:30:00Z"
    }
  }
}

Standard fields:

Setting Up Webhooks

Step 1: Prepare Your Endpoint

Create an HTTP endpoint (webhook URL) that:

• Accepts POST requests
• Can handle JSON payloads
• Returns HTTP 2xx status codes for success
• Verifies webhook signatures (recommended)

Example in Node.js (Express):

app.post('/webhooks/define', (req, res) => {
  const event = req.body.event;
  const data = req.body.data;

  console.log(`Received event: ${event}`);

  // Process the event
  switch(event) {
    case 'definition.created':
      // Handle new definition
      break;
    case 'acronym.deleted':
      // Handle deleted acronym
      break;
  }

  // Acknowledge receipt
  res.status(200).json({ success: true });
});

Step 2: Register Webhook in define.wtf

1. Navigate to Admin → Webhooks (or Settings → Webhooks depending on your version)
2. Click Add Webhook
3. Enter your webhook URL (e.g., https://example.com/webhooks/define)
4. Select which events to subscribe to (or select all)
5. Click Create Webhook

Step 3: Test the Webhook

define.wtf provides a Test button:

1. Go to Admin → Webhooks
2. Find your webhook
3. Click Send Test Event
4. define.wtf sends a test payload to your endpoint
5. Check your logs to verify receipt

Step 4: Monitor and Debug

After creating a webhook:

1. Go to Admin → Webhooks
2. Click your webhook to see delivery history
3. View recent deliveries with timestamps, payloads, and response codes
4. If deliveries are failing, check your endpoint logs

Verifying Webhook Secrets

Each webhook request includes a plaintext secret in the header for authentication:

Secret Verification

The webhook includes this header:

X-Webhook-Secret: your_webhook_secret

Verification steps:

1. Extract the secret from the X-Webhook-Secret header
2. Compare it to your stored webhook secret
3. If they match, the request is from define.wtf
4. If they don't match, reject the request (possible forgery)

Example in Node.js:

function verifyWebhook(req, storedSecret) {
  const headerSecret = req.headers['x-webhook-secret'];

  if (headerSecret !== storedSecret) {
    throw new Error('Invalid webhook secret');
  }

  // Secret verified; process webhook
  return true;
}

Your webhook secret is shown when you create the webhook; store it securely and never commit it to version control.

Delivery Guarantee

define.wtf sends webhooks on a fire-and-forget basis:

• Timeout: 10 seconds per request
• Single attempt: Webhooks are sent once; no automatic retries
• Status codes: Any response is logged (success or failure)
• Logging: All deliveries are recorded for debugging

If your endpoint is unreachable or returns an error:

1. Check your endpoint logs for errors
2. Verify your endpoint is returning HTTP 2xx status codes
3. Test your endpoint with the "Send Test Event" button in the webhook settings
4. Re-send manually from the webhook delivery logs if needed

Common Use Cases

Use Case 1: Slack Notifications

Post new acronyms to a #announcements channel:

1. Set up a webhook for definition.created events
2. Your endpoint receives the event
3. Format the definition as a Slack message
4. Send to Slack via Incoming Webhook
5. Your team sees: "#announcements: New: OKR — A goal-setting framework..."

Implementation: ~30 minutes with Zapier, or 1-2 hours with custom code.

Use Case 2: Activity Dashboard

Build a real-time dashboard of define.wtf activity:

1. Set up webhooks for all events
2. Your endpoint logs each event to a database
3. Dashboard queries the database and displays:
   • Most active today
   • Most voted definitions
   • Recent contributors
   • Trending acronyms

Implementation: 2-4 hours with custom dashboard.

Use Case 3: Automated Data Sync

Keep your internal wiki or knowledge base in sync with define.wtf:

1. Set up webhooks for definition.created and definition.updated events
2. Your endpoint receives events
3. Your system updates the wiki/knowledge base
4. Users always have the latest definitions

Implementation: 1-2 hours depending on target system.

Use Case 4: Approval Workflow

Send new definitions to your team for review before they're published:

1. Set up webhook for definition.created
2. Your endpoint stores the new definition in a pending queue
3. Send email to approvers with review link
4. Approvers approve/reject in your system
5. On approval, publish to define.wtf via API

Implementation: 3-4 hours with custom workflow system.

Use Case 5: Compliance and Audit

Log all changes to a compliance system or SIEM:

1. Set up webhooks for all mutation events
2. Your endpoint sends events to your SIEM (Splunk, Datadog, etc.)
3. Your SIEM creates searchable audit trail
4. Security team can investigate changes and detect anomalies

Implementation: 1-2 hours with pre-built SIEM integrations.

Building Integrations with Zapier

Zapier is a no-code platform that can listen to define.wtf webhooks and trigger actions in hundreds of apps.

Step 1: Create a Zapier "Zap"

1. Log into Zapier
2. Click "Create Zap"
3. Choose "Webhook" as the trigger
4. Zapier provides a webhook URL

Step 2: Register Webhook in define.wtf

1. Copy the Zapier webhook URL
2. In define.wtf Admin → Webhooks, add the webhook
3. Select events to subscribe to
4. Save

Step 3: Test

1. In define.wtf, create a new acronym
2. Zapier receives the webhook event
3. Configure the Zapier action (e.g., send Slack message)
4. Test to verify it works

Step 4: Deploy

1. Enable the Zap
2. define.wtf events now trigger Zapier automations
3. Monitor the Zapier activity log for issues

Example Zaps:

• "When definition created → Post to Slack"
• "When definition created → Add row to Google Sheet"
• "When definition created → Send email to admin"
• "When definition created → Create Monday.com task"

See Also

• Admin Guide: Webhooks — Setup and management
• REST API: Webhook Reference — Technical details
• Integrations: Overview — All integration options