Webhooks

Receive formation and document events, and verify their signatures.

Formation is asynchronous. Rather than polling, subscribe to webhook events to learn when a formation progresses and when documents become available.

Setup

1. Get your signing secret

   doola provisions your tenant and generates your webhook signing secret. It is shown once at creation, so store it securely. Email [e-mail] to get set up or to rotate it.

2. Configure your endpoint

   Set your webhook URL in the doola Partner Portal. The URL must be HTTPS. Each environment has its own tenant, so configure sandbox and production separately.

Verifying the signature

doola sends a POST with an X-Doola-Signature header: an HMAC SHA256 hex digest of the raw request body, keyed with your webhook secret. (HTTP header names are case-insensitive; many frameworks lowercase them to x-doola-signature on the way in.)

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, webhookSecret) {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');
  const expectedBuffer = Buffer.from(expected);
  const signatureBuffer = Buffer.from(signature ?? '');
  // timingSafeEqual throws if the buffers differ in length, so reject that first.
  if (expectedBuffer.length !== signatureBuffer.length) {
    return false;
  }
  return crypto.timingSafeEqual(expectedBuffer, signatureBuffer);
}

Always use a constant time comparison (timingSafeEqual or compare_digest). Plain string equality is vulnerable to timing attacks.

Payload

{
  "eventId": "31pLdpvMh4OfO90moxLgLT8AuQr",
  "eventName": "document_aoo_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31pLdj8SKAU9BYNchcohyto2AxC",
    "documentType": "ArticlesOfOrganization",
    "documentCreatedAt": "2025-08-26 13:49:16.0"
  },
  "timestamp": 1756216157000
}

Events

Event	Description
company_formation_submitted	Formation accepted and processing started
company_formation_completed	Formation complete, company is active
company_formation_failed	Formation failed, check the company’s admin notes
company_filing_date_updated	Filing date was updated by doola
document_aoo_uploaded	Articles of Organization ready to download
document_einletter_uploaded	EIN Letter ready to download
document_mail_uploaded	Business mail document uploaded
partner_webhook_disabled	Your endpoint was automatically disabled (see below)

You may occasionally receive duplicate document_* events for the same document, for example after doola re-issues a document. Handle uploads idempotently using documentId.

Delivery and retries

If your endpoint does not return a 2xx, doola retries up to 5 times: at 1 minute, 15 minutes, 1 hour, 12 hours, and 24 hours after the previous attempt. Treat every delivery as at least once.

After all retries fail, doola automatically disables your endpoint and sends a final partner_webhook_disabled event. Fix your endpoint and re-enable it in the Partner Portal. Re-enabling is a deliberate partner action, so you confirm the endpoint is healthy before traffic resumes.

Every delivery attempt (timestamp, event, HTTP status, attempt number) is visible in the Partner Portal.