Webhook Developer Guide

Greenstamp webhooks let you receive real-time, signed event notifications the moment things happen in your account — invoice stamped, bill paid, certificate expiring — without polling the API.

Overview

Webhooks are push-based: you register an HTTPS endpoint, and Greenstamp POSTs a signed JSON payload to it whenever a subscribed event occurs. This is the inverse of the REST API, where you pull data on demand.

If you need to query historical events or fill a gap after downtime, you can reconcile against the pull-based Events API — use X-Webhook-ID as a correlation key.

Getting started

1. Register an endpoint — go to Settings → Webhooks in the app, or use the webhook_endpoints REST resource. Provide a public HTTPS URL and select which event types to subscribe to.
2. Save your secret — after creation, you are shown a signing secret once. Copy it immediately; Greenstamp stores only a derived hash and cannot reveal the original again. You can rotate it later if needed.
3. Deploy your receiver — a minimal receiver needs to verify the X-Webhook-Signature header (see Verifying signatures) and return 200 OK.

The request we send

Headers

Every delivery is an HTTP POST with Content-Type: application/json. The following headers are always present:

Payload shape

Every event envelope has the same top-level shape. The data field contains event-specific attributes.

{
  "id":          "evt_AbCdEfGh1234567890abcdef",   // unique event ID (same as X-Webhook-ID event part)
  "type":        "invoice.stamped",                  // event type — see Event catalog
  "created_at":  "2024-06-07T10:30:00Z",             // ISO 8601 UTC
  "api_version": "v1",
  "entity": {
    "id":         "entt_...",                        // the entity this event concerns
    "legal_name": "Acme SA de CV"
  },
  "data": { ... }                                    // event-specific payload (see below)
}

Example — invoice.stamped

{
  "id":          "evt_AbCdEfGh1234567890abcdef",
  "type":        "invoice.stamped",
  "created_at":  "2024-06-07T10:30:00Z",
  "api_version": "v1",
  "entity": {
    "id":         "entt_Xy9mNpQ3rsTu",
    "legal_name": "Acme SA de CV"
  },
  "data": {
    "id":       "inv_Lm4kP8vWzXqR",
    "folio":    "A-0042",
    "status":   "stamped",
    "total":    116000,
    "currency": "MXN",
    "counterparty": {
      "id":   "cpty_Rn7tBxYcVdEs",
      "name": "Globex Corp"
    }
  }
}

Verifying signatures

The exact recipe

Greenstamp signs each delivery as follows. You must reproduce this exactly — a single-character difference produces a completely different signature.

1. Derive the signing key — the server does not sign with your raw secret directly. It signs with SHA256(raw_secret). The raw secret is the 64-character hex string you copied at creation time.
   
   key = SHA256_hex(raw_secret)      # 64-char hex → 64-char hex
2. Build the signed string — concatenate the X-Webhook-Timestamp value, a literal dot, and the raw request body bytes (do not re-serialize the JSON):
   
   message = X-Webhook-Timestamp + "." + request_body
3. Compute the HMAC:
   
   expected = HMAC-SHA256(key, message) # as lowercase hex
4. Compare with constant-time equality — use your language's timing-safe compare to avoid timing attacks.

Code examples

require 'openssl'
require 'digest'

# raw_secret   — the 64-char hex string shown at webhook creation
# timestamp    — X-Webhook-Timestamp header value (string)
# body         — raw request body (string, NOT re-parsed JSON)
# sig_header   — X-Webhook-Signature header value
def verify_webhook(raw_secret, timestamp, body, sig_header)
  # Step 1: derive the signing key the same way the server does
  key = Digest::SHA256.hexdigest(raw_secret)

  # Step 2: build the signed string
  message = "#{timestamp}.#{body}"

  # Step 3: compute HMAC-SHA256
  expected = OpenSSL::HMAC.hexdigest('SHA256', key, message)

  # Step 4: constant-time compare (Rails / ActiveSupport)
  ActiveSupport::SecurityUtils.secure_compare(sig_header, expected)
end

# In a Rails controller:
def create
  timestamp  = request.headers['X-Webhook-Timestamp']
  signature  = request.headers['X-Webhook-Signature']
  body       = request.raw_post

  # Reject if timestamp is more than 5 minutes old
  if (Time.now.to_i - timestamp.to_i).abs > 300
    head :forbidden and return
  end

  unless verify_webhook(ENV['GREENSTAMP_WEBHOOK_SECRET'], timestamp, body, signature)
    head :forbidden and return
  end

  event = JSON.parse(body)
  # process event...
  head :ok
end

const crypto = require('crypto');

// rawSecret   — the 64-char hex string shown at webhook creation
// timestamp   — X-Webhook-Timestamp header value (string)
// body        — raw request body (string, NOT re-parsed JSON)
// sigHeader   — X-Webhook-Signature header value
function verifyWebhook(rawSecret, timestamp, body, sigHeader) {
  // Step 1: derive the signing key the same way the server does
  const key = crypto.createHash('sha256').update(rawSecret).digest('hex');

  // Step 2: build the signed string
  const message = `${timestamp}.${body}`;

  // Step 3: compute HMAC-SHA256
  const expected = crypto.createHmac('sha256', key).update(message).digest('hex');

  // Step 4: constant-time compare
  try {
    return crypto.timingSafeEqual(
      Buffer.from(sigHeader, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false; // mismatched lengths or bad hex
  }
}

// Express middleware example:
app.post('/webhooks/greenstamp', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];
  const body      = req.body.toString(); // raw bytes → string

  // Reject if timestamp is more than 5 minutes old
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.sendStatus(403);
  }

  if (!verifyWebhook(process.env.GREENSTAMP_WEBHOOK_SECRET, timestamp, body, signature)) {
    return res.sendStatus(403);
  }

  const event = JSON.parse(body);
  // process event...
  res.sendStatus(200);
});

Replay protection

The X-Webhook-Timestamp header lets you detect and reject replayed requests. The examples above reject any delivery older than 5 minutes — adjust the window to fit your SLA, but keep it short enough to prevent replay attacks.

For an additional layer of replay protection, store processed X-Webhook-ID values and reject duplicates (see Best practices).

Event catalog

Greenstamp emits 28 event types across 6 domains. The list below is generated from the model constants — it updates automatically when new event types are added.

Invoices

Bills

Credit Notes

Payments

Entities

Counterparties

Retries & failure handling

Greenstamp considers any 2xx response a success. Any other response — including timeouts — is treated as a failure and triggers the retry schedule.

Retry schedule

Each delivery gets up to 5 attempts total (1 initial + 4 retries). If all 5 fail, the delivery is marked failed permanently.

Auto-disable

If a destination accumulates 10 consecutive failures with no successful delivery in between, it is automatically disabled with reason "Automatically disabled after 10 consecutive failures". You will need to re-enable it manually from the Webhooks UI or via the API after the issue is resolved.

Request timeout

Greenstamp waits up to 30 seconds for a response (10-second connection timeout). If your handler needs more time, acknowledge immediately with 200 OK and do the work asynchronously — see Best practices.

Delivery log

Every attempt is logged in the Webhooks UI: status, response code, response body, and latency. Use this to debug failed deliveries and inspect exact payloads.

Building a reliable receiver

• Respond 200 OK immediately, process async. Greenstamp waits 30 seconds max. If your handler touches a database, calls downstream APIs, or sends emails, offload that work to a background job and return 200 right away. Timeouts count as failures and consume retry slots.
• Deduplicate on X-Webhook-ID. Retries send the same delivery ID. Store processed IDs and skip re-processing if you see a duplicate. This makes your handler idempotent against both retries and any unexpected duplicates.
• Tolerate unknown event types. Greenstamp may add new event types in the future. If your handler only processes known types, return 200 for unknowns rather than 400 — returning non-2xx for an unknown event type causes it to be retried unnecessarily and can contribute to auto-disable.
• Reject stale timestamps. Reject deliveries where X-Webhook-Timestamp is more than 5 minutes old (or your chosen window). This prevents an attacker who has intercepted a delivery from replaying it later.
• Reconcile via the Events API after downtime. If your endpoint was down during a retry window, some events may be permanently failed. Use the Events API to pull the missed events by time range and reconcile your state.
• Use HTTPS with a valid certificate. Greenstamp only delivers to https:// endpoints with a valid TLS certificate. Self-signed certificates are rejected. Greenstamp also blocks delivery to private IP ranges (RFC 1918) and loopback addresses.

Related: REST API Reference · MCP / Agent Tools