Webhooks

Webhooks let you receive real-time HTTP notifications when events happen in RAMSdoc. Use them to integrate RAMSdoc with your other systems — for example, updating a project management tool when a document is approved, or triggering a notification when a contractor submits their RAMS.

Note

Webhook configuration is available on Enterprise plans. Pro and Team plans can receive webhook events via the API polling approach described in polling.

Configuring a webhook

1. Go to Settings > API > Webhooks.
2. Click Add Webhook.
3. Enter:
   • URL — the HTTPS endpoint that will receive webhook payloads
   • Events — which events to subscribe to (see events below)
   • Secret — a shared secret used to verify webhook signatures
4. Click Save.

RAMSdoc sends a test event to verify your endpoint is reachable. Your endpoint must respond with a 200 status code within 10 seconds.

Via the API

curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-app.example.com/webhooks/ramsdoc",
       "events": ["document.approved", "document.submitted", "contractor.submitted"],
       "secret": "your_webhook_secret"
     }' \
     "https://api.ramsdoc.com/api/v1/webhooks"

Events

Event	When it fires
document.created	A new document is created
document.updated	A document is edited
document.submitted	A document is submitted for review
document.approved	A document is approved
document.rejected	A document is rejected with amendments requested
document.exported	A document is exported to PDF/DOCX
contractor.invited	A contractor is invited to a project
contractor.submitted	A contractor submits their RAMS for review
signoff.recorded	A worker signs off on a document briefing
incident.reported	An incident or near-miss is reported
permit.opened	A permit to work is opened on site
permit.closed	A permit to work is closed
compliance.scored	A compliance check completes
certification.expiring	A team member’s certification is approaching expiry

Payload format

Webhook payloads are sent as JSON POST requests:

{
  "event": "document.approved",
  "timestamp": "2026-03-25T14:30:00Z",
  "data": {
    "document_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "title": "RAMS — Cable Tray Installation, Building A",
    "reference": "RAMS-202603-001",
    "version": 2,
    "approved_by": {
      "id": "...",
      "name": "Sarah Johnson"
    },
    "project_id": "...",
    "organisation_id": "..."
  }
}

The data object varies by event type but always includes the relevant resource IDs.

Verifying signatures

Every webhook request includes a signature header so you can verify it came from RAMSdoc:

X-RAMSdoc-Signature: sha256=abc123...

Verify the signature by computing an HMAC-SHA256 of the raw request body using your webhook secret:

JavaScript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Caution

Always verify webhook signatures before processing the payload. Without verification, an attacker could send fake events to your endpoint.

Retry behaviour

If your endpoint does not respond with a 2xx status code within 10 seconds, RAMSdoc retries:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed retries, the event is marked as failed. You can view failed deliveries and retry them manually in Settings > API > Webhooks > Delivery Log.

If your endpoint fails consistently (10+ consecutive failures), the webhook is automatically disabled and you receive an email notification.

Polling as an alternative

If your plan does not include webhooks, you can poll for changes:

# List recent document activity
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.ramsdoc.com/api/v1/documents?updated_since=2026-03-25T00:00:00Z"

# List recent notifications
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.ramsdoc.com/api/v1/notifications"

Poll at reasonable intervals (every 1-5 minutes) to stay within rate limits.

Best practices

• Respond quickly — return a 200 immediately and process the event asynchronously. Do not do heavy processing in the webhook handler.
• Handle duplicates — in rare cases, the same event may be delivered twice. Use the event timestamp and resource ID to detect duplicates.
• Verify signatures — always verify the X-RAMSdoc-Signature header before processing.
• Use HTTPS — webhook URLs must use HTTPS. HTTP endpoints are not accepted.
• Monitor deliveries — check the delivery log periodically to ensure events are being received.