Skip to main content
Moonbase webhooks enable real-time notifications about events in Moonbase, such as when an item is created, when a program message is opened, or a meeting is held. Webhooks are delivered to a configured HTTP endpoint.

​
Quick Start

Creating your first webhook with Moonbase.

​
1. Create an endpoint

Use the Webhooks API to register the webhook endpoint: 
curl -X POST https://api.moonbase.ai/v0/webhook_endpoints \
  -H "Authorization: Bearer MOONBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/moonbase",
    "subscriptions": [
      {"event_type": "activity/item_created"},
      {"event_type": "activity/meeting_held"}
    ]
  }'
The response will include the endpoint’s unique secret (prefixed with whsec_). Store this secret securely—required to verify incoming webhooks. This is the only time the secret will be shown.

​
2. Expose an HTTPS route

Webhook endpoints must:
  • Be publicly accessible via HTTPS
  • Accept POST requests with application/json content
  • Respond within 30 seconds to avoid timeouts

​
3. Verify the signature

Always verify the webhook signature before processing any data. This ensures:
  • The request genuinely comes from Moonbase
  • The payload hasn’t been tampered with
  • Protection against replay attacks
Key requirements:
  • Use the raw request body (before JSON parsing)
  • Verify the signature before any other processing
  • Reject requests with invalid signatures immediately
See the signature verification section for implementation details.

​
4. Process the payload

After successful verification, parse and process the JSON payload.

​
5. Respond promptly

Return a 2XX status code (typically 200 or 204) to acknowledge receipt:
  • Respond as quickly as possible (within 30 seconds)
  • Process time-consuming operations asynchronously
If Moonbase doesn’t receive a 2XX response, it will retry delivery according to the retry schedule.

​
Configuration

Additional configurations for webhooks.

​
Payload Format

Each payload includes:
  • id: Unique event identifier
  • occurred_at: ISO 8601 timestamp indicating when the event occurred.
  • type: Event type (e.g., activity/item_created)
  • Related objects (item, collection, etc.)
Example Payload
{
  "id": "1CLJt2v2bnDhMVZzehdb6A",
  "occurred_at": "2025-02-17T15:59:55.000Z",
  "type": "activity/item_created",
  "item": {
    "id": "1CLJt2uzNLR8B4AnQ3vJ3B",
    "type": "item",
    "collection": {
      "id": "1CLJt2uzcick5mf96Lzt9x",
      "type": "collection",
      "ref": "people"
    }
  }
}

​
Verifying webhook signatures

Never process webhook data without first verifying its authenticity. Verification ensures that the request came from Moonbase and hasn’t been tampered with.

​
How signatures work

Moonbase uses the Standard Webhooks specification for signing webhooks:
  1. Each endpoint has a unique signing secret (format: whsec_0{version}{44-char-base58})
  2. Every webhook request includes an HMAC-SHA256 signature in the webhook-signature header
  3. The signature covers the event ID, timestamp, and raw request body
The signature algorithm: 
signature = HMAC-SHA256(secret, `${webhook_id}.${webhook_timestamp}.${raw_payload}`)

​
Security best practices

  1. Store secrets securely: Use environment variables or a secrets management service—never commit secrets to version control
  2. Use raw request bodies: The signature is computed on the exact bytes sent—any modification (even whitespace) will cause verification to fail
  3. Verify timing: Check that the timestamp is recent (within 5 minutes) to prevent replay attacks
  4. Reject failures: If verification fails for any reason, reject the request with a 400 or 401 status
  5. Log failures: Monitor verification failures as they may indicate security issues

​
HTTP Headers

Webhook requests include the following Standard Webhooks headers:
  • webhook-id: Event ID (used for idempotency and doesn’t change between retries)
  • webhook-timestamp: Unix timestamp when the request was sent
  • webhook-signature: HMAC-SHA256 signature for verification
  • content-type: application/json

​
Delivery and Retry Logic

Moonbase ensures reliable webhook delivery with automatic retries and intelligent backoff strategies.

​
Response handling

The endpoint’s HTTP response determines how Moonbase handles the delivery:
Status CodeBehaviorNotes
2XXSuccessDelivery marked complete, no retries
410 GonePermanent failureEndpoint automatically disabled, no retries
429 Too Many RequestsRate limitedHonors Retry-After header if present
All other non-2XXTemporary failureAutomatic retry with exponential backoff

​
Retry schedule

Failed deliveries are retried for up to 24 hours using exponential backoff with 10% jitter to prevent thundering herd issues:
AttemptDelayCumulative TimeNotes
1Immediate0 secondsInitial delivery
2~30 seconds~30 seconds30s + random jitter (0-3s)
3~1 minute~1.5 minutes60s + random jitter (0-6s)
4~2 minutes~3.5 minutes120s + random jitter (0-12s)
5~4 minutes~7.5 minutes240s + random jitter (0-24s)
6~8 minutes~15.5 minutes480s + random jitter (0-48s)
7~16 minutes~31.5 minutes960s + random jitter (0-96s)
8~32 minutes~1 hour1920s + random jitter (0-192s)
9+~1 hourVaries3600s + random jitter (0-360s), capped
Key points:
  • Maximum individual retry delay: 1 hour
  • Total retry window: 24 hours
  • Jitter: 10% of base delay to distribute load
  • Guaranteed: At least one delivery attempt per hour during the retry window

​
Handling failures

To minimize failed deliveries:
  1. Respond quickly: Return a 2XX status within 30 seconds
  2. Implement idempotency: Use the webhook-id header to handle duplicate deliveries
  3. Monitor endpoint: Track success rates and response times
  4. Use proper status codes: Return 410 if the endpoint is permanently decommissioned
  5. Handle rate limits: Return 429 with Retry-After header if you need to throttle

​
Idempotency

Webhooks guarantee at-least-once message delivery. Moonbase includes a webhook-id header containing a unique identifier for each event. This ID remains the same across all retry attempts for a failed webhook, enabling applications to handle duplicate deliveries by tracking processed event IDs.

​
Data Retention

Event payloads and delivery response data are retained for 30 days before being automatically purged from Moonbase systems. This retention period allows for webhook replay and troubleshooting while maintaining data privacy compliance.