Webhooks

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

Setup

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 engineering@doola.com to get set up or to rotate it.

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.

To see real deliveries end to end without waiting on an actual formation, use the Sandbox playground: it completes the formation and EIN milestones on demand and fires the events below through the normal pipeline.

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.)

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);
}

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    expected = hmac.new(
        webhook_secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

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

Payload

Every delivery is a POST with the same envelope. Only eventPayload changes shape from event to event.

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

Field	Type	Description
`eventId`	string	Unique ID for this event. Use it to dedupe redeliveries.
`eventName`	string	Which event fired (see the table below).
`eventPayload`	object \| null	Event-specific body. Shape depends on `eventName`, and is `null` for `partner_webhook_disabled`.
`timestamp`	number	When the event fired, Unix epoch in milliseconds.

Events

Event	Description
`company_formation_submitted`	Formation accepted and processing started
`company_formation_completed`	Formation complete, company is active
`company_formation_failed`	Formation failed after all retries; inspect `reasonCode` and `message`
`company_filing_date_updated`	Filing date was updated by doola
`company_ein_issued`	The company’s EIN was issued; fetch the company to read `ein`
`document_aoo_uploaded`	Articles of Organization ready to download
`document_einletter_uploaded`	EIN Letter ready to download
`document_mail_uploaded`	Business mail document uploaded
`document_corporatebylaws_uploaded`	Corporate Bylaws ready to download (CCorp only)
`document_operatingagreement_uploaded`	Operating Agreement ready to download (LLC only)
`signature_ss4_completed`	A non-US founder signed their SS-4
`document_ss4_uploaded`	Signed SS-4 stored and ready to download
`signature_ss4_reminder_due`	An unsigned SS-4 is due a reminder (day 1, 3, 7)
`signature_form8821_completed`	A non-US founder on an expedited EIN signed their Form 8821
`document_form8821_uploaded`	Signed Form 8821 stored and ready to download
`signature_form8821_reminder_due`	An unsigned Form 8821 is due a reminder (day 1, 3, 7)
`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.

The three SS-4 events fire only for non-US founders, who must sign an SS-4 before the IRS issues the EIN. The three form8821 events mirror them and fire only for a non-US founder who also requested an expedited EIN, where a signed Form 8821 authorizes doola to retrieve the EIN letter from the IRS. In each pair, signature_*_completed fires the instant the founder signs; document_*_uploaded fires once the signed PDF is stored and downloadable. See Non-US founders for the full flow.

company_ein_issued and document_einletter_uploaded both signal EIN issuance, at two distinct moments: company_ein_issued fires when doola records the EIN on the company (fetch the company to read the ein field), and document_einletter_uploaded fires once the IRS confirmation letter is stored and downloadable. They arrive independently, so do not assume an order. company_ein_issued fires only on the first issuance; a later correction to the EIN value does not re-fire it.

The two governance-document events are entity-type specific: document_corporatebylaws_uploaded fires for CCorp companies only, and document_operatingagreement_uploaded fires for LLC companies only. doola generates the governance document shortly after the Articles of Organization are processed, so each event typically arrives soon after document_aoo_uploaded.

Example payloads

A sample delivery for every event. Within eventPayload, only the fields relevant to that event are present; inapplicable fields are omitted entirely rather than sent as null, so parse defensively. eventPayload itself is null only for partner_webhook_disabled.

company_formation_submitted

{
  "eventId": "31pLeQk8Mcp7rSflgdr1c2ZV2th",
  "eventName": "company_formation_submitted",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ"
  },
  "timestamp": 1756216100000
}

company_formation_completed

{
  "eventId": "31q8RtBnVGPk26B6ZqeUFeAaMBE",
  "eventName": "company_formation_completed",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ"
  },
  "timestamp": 1756392000000
}

company_formation_failed

{
  "eventId": "31qC2fK9mNpL7vWxYzAbCdEfGhJ",
  "eventName": "company_formation_failed",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "doolaCustomerId": "31pLCw7sN2aQ9fJkRtY3vXbHmLe",
    "reasonCode": "FORMATION_SUBMISSION_FAILED",
    "message": "Doola formation submission failed after the configured retry budget. Please contact support."
  },
  "timestamp": 1756220000000
}

company_filing_date_updated

{
  "eventId": "31qF5gH3kMqR8sT2uVwXyZaBcDe",
  "eventName": "company_filing_date_updated",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ"
  },
  "timestamp": 1756300000000
}

company_ein_issued

{
  "eventId": "31wZ4rY6tA3fSkPqWxD8bCgMrQj",
  "eventName": "company_ein_issued",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ"
  },
  "timestamp": 1756750000000
}

document_aoo_uploaded

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

document_einletter_uploaded

{
  "eventId": "31rT8gH9kM4qR2sTuVwXyZaBcDf",
  "eventName": "document_einletter_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31rTm4kP9nQ2aLfJkRtY3vXbHmL",
    "documentType": "EinLetter",
    "documentCreatedAt": "2025-09-02 08:11:42.0"
  },
  "timestamp": 1756800702000
}

document_mail_uploaded

{
  "eventId": "31sV2kP7nQ9aLfJkRtY3vXbHmLg",
  "eventName": "document_mail_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31sVq8nT6kM4qR2sTuVwXyZaBcD",
    "documentType": "Mail",
    "documentCreatedAt": "2025-09-10 17:05:30.0"
  },
  "timestamp": 1757523930000
}

document_corporatebylaws_uploaded

{
  "eventId": "31tC3nS7qT9eMhNoPvX5zFgLrSm",
  "eventName": "document_corporatebylaws_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31tC7rY8wB2fNiOpQwA7aGhMsTn",
    "documentType": "CorporateBylaws",
    "documentCreatedAt": "2025-08-26 13:52:41.0"
  },
  "timestamp": 1756216361000
}

document_operatingagreement_uploaded

{
  "eventId": "31tC5pU9xD4gOjPqRsB8bHiNtUo",
  "eventName": "document_operatingagreement_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31tC9sZ0yE6hPkQrTwC9cJjOuVp",
    "documentType": "OperatingAgreement",
    "documentCreatedAt": "2025-08-26 13:53:07.0"
  },
  "timestamp": 1756216387000
}

signature_ss4_completed

{
  "eventId": "31tW5mR3pS7bMgKlSuZ4wYcInMf",
  "eventName": "signature_ss4_completed",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ"
  },
  "timestamp": 1756250000000
}

document_ss4_uploaded

{
  "eventId": "31tW9nT6qU8cNhLmTvA5xZdJoNg",
  "eventName": "document_ss4_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31tWp2rX5sZ7bMgKlSuZ4wYcInM",
    "documentType": "SignedSS4",
    "documentCreatedAt": "2025-08-27 10:22:09.0"
  },
  "timestamp": 1756290129000
}

signature_ss4_reminder_due

{
  "eventId": "31uX1pV4rW9dOiMnUwB6yAeKpOh",
  "eventName": "signature_ss4_reminder_due",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "message": "SS4 signature is still pending. Request a fresh signing URL and re-present it to the user.",
    "documentType": "SS4",
    "daysSinceRequested": 1
  },
  "timestamp": 1756160000000
}

signature_form8821_completed

{
  "eventId": "31vA2qW5sT8dPjNoVxC7zBfLqPi",
  "eventName": "signature_form8821_completed",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ"
  },
  "timestamp": 1756250050000
}

document_form8821_uploaded

{
  "eventId": "31vB6rY8tV0eQkOpWyD8aCgMrQj",
  "eventName": "document_form8821_uploaded",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "documentId": "31vBq3sZ7tA9cNhLmTvA5xZdJoN",
    "documentType": "SignedForm8821",
    "documentCreatedAt": "2025-08-27 10:24:41.0"
  },
  "timestamp": 1756290281000
}

signature_form8821_reminder_due

{
  "eventId": "31vC4sZ7uX1fRlPqXzE9bDhNsRk",
  "eventName": "signature_form8821_reminder_due",
  "eventPayload": {
    "doolaCompanyId": "31pLD0Tq2lm2FsgRBoHv4x3BpzZ",
    "message": "Form 8821 signature is still pending. Request a fresh signing URL and re-present it to the user.",
    "documentType": "FORM8821",
    "daysSinceRequested": 1
  },
  "timestamp": 1756160050000
}

partner_webhook_disabled

{
  "eventId": "31vY3qX5sZ2eRjNoVxC7zBfLqPi",
  "eventName": "partner_webhook_disabled",
  "eventPayload": null,
  "timestamp": 1756600000000
}

Payload fields

doolaCompanyId is on every company- and document-scoped payload. The rest appear only on the events noted below:

Field	Appears in	Meaning
`documentId`	`document_*`	ID of the uploaded document. Use it with the document endpoints to download.
`documentType`	`document_*`, `signature_ss4_reminder_due`, `signature_form8821_reminder_due`	`ArticlesOfOrganization`, `EinLetter`, `Mail`, `CorporateBylaws`, `OperatingAgreement`, `SignedSS4`, or `SignedForm8821` on document events; `SS4` or `FORM8821` on the matching reminder.
`documentCreatedAt`	`document_*`	When doola stored the document.
`doolaCustomerId`	`company_formation_failed`	The customer who owns the company. Best-effort; omitted if unavailable.
`reasonCode`	`company_formation_failed`	Machine-readable failure reason. Branch on this, never on `message`.
`message`	`company_formation_failed`, `signature_ss4_reminder_due`, `signature_form8821_reminder_due`	Human-readable context for the event.
`daysSinceRequested`	`signature_ss4_reminder_due`, `signature_form8821_reminder_due`	Days since that document was first requested: `1`, `3`, or `7`.

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.

Get started

Core concepts

Reference

API reference

Help

Updates

Setup

Verifying the signature

Payload

Events

Example payloads

Payload fields

Delivery and retries

​Setup

​Verifying the signature

​Payload

​Events

​Example payloads

​Payload fields

​Delivery and retries

Setup

Verifying the signature

Payload

Events

Example payloads

Payload fields

Delivery and retries