Webhooks allow you to receive real-time HTTP notifications when events occur in Drum. Instead of polling the API for changes, you can subscribe to specific events and Drum will push data to your endpoint automatically.

Drum will generate a unique secret key for signature verification. Copy and store this securely - you'll need it to verify incoming webhooks.

Opportunities are stored as projects with project_type: "opportunity", so project.created and project.updated fire for opportunities as well as for delivery projects. Use the project_type attribute in the payload to tell them apart.

project.completed fires for delivery projects only (project_type: "project"), in the same save as project.updated. It fires once for each move into a complete status: a move between two complete statuses, or an edit of completed_date, does not fire it again. Moving the project back to a status that is not complete clears completed_date and fires only project.updated. Opportunities never fire project.completed.

Completion events are sent after the transaction commits and contain the state at the completion transition. A later save in that transaction does not erase the event or change its payload. A rolled-back transition sends no event. Updates made while creating a project are included in project.created instead of separate update or completion events.

opportunity.won and opportunity.lost fire once per outcome: the first time the relevant date moves from empty to set. Moving a won opportunity back to a standard status clears the date and fires only project.updated; a later move back to won fires opportunity.won again.

Converting an opportunity into a project emits three events: project.created for the new project, plus project.updated and opportunity.won for the opportunity. Delivery order is not guaranteed. Correlate them with the opportunity_id attribute on the new project, which holds the id of the opportunity it was converted from.

Drum groups the .updated events of one record (project.updated, invoice.updated, cost.updated) over a 5-second window:

You do not always get one event for each save, but after a burst of changes Drum sends the state of the record when the burst ends. Retries and network delays can deliver events out of order, so keep the event with the latest data.attributes.updated_at for each record. A save that changes only the record's timestamp (for example, when a booking or milestone on the project changes) sends no event. .created events, project.completed, opportunity.won and opportunity.lost are not combined.

Webhook timestamps include six fractional-second digits, so distinct saves within the same second can be ordered by data.attributes.updated_at. Date-only attributes such as completed_date remain YYYY-MM-DD.

A budget spreadsheet import into a project sends one project.updated when it finishes, with the new totals. It does not send an event for each deliverable or task that it creates.

Duplicate Project does not emit project.created (or other project webhooks). Event Triggers for Project created do fire on duplicate; webhooks do not. See How to duplicate a project.

All webhooks are sent as HTTP POST requests with a JSON body.

{
"event": "project.created",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"id": 12345,
"type": "Project",
"attributes": {
// Event-specific attributes
}
}
}

project.created, project.updated, project.completed, opportunity.won, and opportunity.lost all use the project payload and include these attributes:

{
"event": "project.created",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"id": 12345,
"type": "Project",
"attributes": {
"id": 12345,
"name": "Office Renovation",
"project_number": "PRJ-2025-001",
"project_type": "project",
"start_date": "2025-01-15",
"end_date": "2025-06-30",
"completed_date": null,
"currency": "AUD",
"total_budget_cents": 15000000,
"total_invoiced_cents": 5000000,
"costs_to_date_cents": 3500000,
"team_id": 42,
"client_id": 789,
"status": "In Progress",
"complete_status": false,
"client_name": "Acme Corporation",
"team_name": "Engineering",
"opportunity_id": 12001,
"opportunity_number": "OPP-2025-014",
"deal_won_date": null,
"deal_lost_date": null,
"lead_score": null,
"sales_status_type": "standard",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}
}

The payload never includes the opportunity's estimated amount, final deal amount, or estimated deposit.

invoice.created and invoice.updated include these attributes:

{
"event": "invoice.created",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"id": 5678,
"type": "Invoice",
"attributes": {
"id": 5678,
"invoice_number": "INV-2025-001",
"project_id": 12345,
"project_number": "PRJ-2025-001",
"status": "sent",
"currency": "AUD",
"total_cents": 550000,
"total_excluding_tax_cents": 500000,
"paid_date": null,
"issued_date": "2025-01-15",
"due_date": "2025-02-14",
"amount_paid_cents": 0,
"reference": "Progress Claim #1",
"description": "January progress claim",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}
}

cost.created and cost.updated include these attributes:

{
"event": "cost.created",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"id": 9012,
"type": "Cost",
"attributes": {
"id": 9012,
"name": "Steel materials",
"project_id": 12345,
"project_number": "PRJ-2025-001",
"task_id": 456,
"status": "approved",
"billing_status": "billable",
"currency": "AUD",
"total_cents": 110000,
"total_excluding_tax_cents": 100000,
"issued_date": "2025-01-10",
"due_date": "2025-02-10",
"paid_date": null,
"invoice_number": "SUP-12345",
"reference": "PO-2025-042",
"description": "Structural steel for level 2",
"supplier_id": 789,
"supplier_type": "Company",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}
}

Every webhook includes an HMAC-SHA256 signature in the X-Webhook-Signature header. You should always verify this signature to ensure the webhook came from Drum and hasn't been tampered with.

The signature is computed as:

signature = HMAC-SHA256(timestamp + "." + payload, secret)
header = "sha256=" + signature

def verify_webhook(request, secret)
signature = request.headers["X-Webhook-Signature"]
timestamp = request.headers["X-Webhook-Timestamp"]
payload = request.raw_post
​
expected_signature = "sha256=" + OpenSSL::HMAC.hexdigest(
"sha256",
secret,
[timestamp, payload].join(".")
)
​
ActiveSupport::SecurityUtils.secure_compare(signature, expected_signature)
end

import hmac
import hashlib
​
def verify_webhook(headers, body, secret):
signature = headers.get("X-Webhook-Signature")
timestamp = headers.get("X-Webhook-Timestamp")
​
signed_payload = f"{timestamp}.{body}"
expected = "sha256=" + hmac.new(
secret.encode(),
signed_payload.encode(),
hashlib.sha256
).hexdigest()
​
return hmac.compare_digest(signature, expected)

const crypto = require('crypto');
​
function verifyWebhook(headers, body, secret) {
const signature = headers['x-webhook-signature'];
const timestamp = headers['x-webhook-timestamp'];
​
const signedPayload = `${timestamp}.${body}`;
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
​
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}

Check the X-Webhook-Timestamp header and reject webhooks older than a few minutes:

def webhook_fresh?(timestamp, tolerance: 5.minutes)
webhook_time = Time.at(timestamp.to_i)
webhook_time > tolerance.ago
end

If your endpoint returns a non-2xx response or times out, Drum will retry the delivery:

After 10 consecutive failures across all deliveries, your webhook subscription will be automatically disabled to prevent resource waste. You'll receive an email notification when this happens.

Return a 2xx response as soon as you receive the webhook. Process the data asynchronously if needed:

def webhooks
# Verify signature first
return head :unauthorized unless verify_webhook(request, ENV["DRUM_WEBHOOK_SECRET"])
​
# Queue for async processing
WebhookProcessorJob.perform_later(params.to_json)
​
head :ok
end

Webhooks may be delivered more than once. Use the X-Webhook-Delivery-Id header to deduplicate:

def process_webhook(delivery_id, payload)
return if ProcessedWebhook.exists?(delivery_id: delivery_id)
​
ProcessedWebhook.create!(delivery_id: delivery_id)
# Process the webhook...
end

Store the raw webhook payload before processing. This helps with debugging and reprocessing if needed.

You can pause a webhook subscription from the Drum UI. Paused subscriptions don't receive events but retain their configuration.

If your secret is compromised, regenerate it from the subscription settings. Update your endpoint with the new secret immediately - the old secret will stop working.

Each subscription shows recent delivery attempts with:

You can retry failed deliveries from the UI.

Your subscription may be auto-disabled after 10 consecutive failures. To re-enable:

The failure counter resets on the next successful delivery.

If you're seeing timeout errors: