> ## Documentation Index > Fetch the complete documentation index at: https://docs.nextlevelmca.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook subscription > Registers an HTTPS endpoint and returns the signing `secret` **once**. **Delivery.** Each event is a `POST` with a JSON body `{ id, type, created_at, location_id, data }` and the headers `Content-Type: application/json`, `User-Agent: NextLevelMCA-Webhooks/1.0`, `X-NLMCA-Event` (the type), `X-NLMCA-Delivery` (unique per attempt group — use it to de-duplicate) and `X-NLMCA-Signature: t=,v1=`. **Verification.** Compute `HMAC-SHA256(secret, t + "." + rawBody)` over the raw request body (before JSON parsing), compare it to `v1` in constant time, and reject when `t` is more than 5 minutes from your clock. Example (Node): `crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")`. **Retries.** Answer 2xx within 10 seconds. Any other response, a redirect or a timeout is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then the delivery is marked dead (replayable from Settings → Developers). Deliveries are at-least-once and may arrive out of order. **Disabling.** A subscription that has failed continuously for 3 days is set to `disabled` and the location admins are emailed. Fix the endpoint, then re-enable it from Settings → Developers → Webhooks. `POST /v1/webhooks/{id}/test` checks an endpoint without waiting for a real event. ## OpenAPI ````yaml /openapi/public-v1.json post /v1/webhooks openapi: 3.0.0 info: title: NextLevel MCA Public API description: >- REST API for the NextLevel MCA deal platform. Objects flow Businesses → People → Deals → Submissions → Offers → Advances. **Authentication.** Send `Authorization: Bearer ` with an API key (`nlmca_live_…`, created in Settings → Developers) or an OAuth access token. Keys are scoped to one location. **Conventions.** JSON only. Cursor pagination (`limit` ≤ 100, `cursor` from `meta.next_cursor`). Every success is `{ data, meta }`; every error is `{ error: { type, message, code, param, request_id } }`. POST endpoints accept `Idempotency-Key` (24h replay). Rate limit 300 requests/min per credential (`X-RateLimit-*` headers). **Scopes.** Keys with no scopes have all of them. Otherwise: - `businesses:read` — Read businesses and their notes, tasks and activity - `businesses:write` — Create and update businesses, notes and tasks - `people:read` — Read people (contacts and owners) - `people:write` — Create and update people - `deals:read` — Read deals, submissions and the pipeline - `deals:write` — Create and update deals, move stages - `documents:read` — Read documents and statement analysis - `documents:write` — Upload documents and request documents from merchants - `lenders:read` — Read lenders, criteria and lender matches - `lenders:write` — Create and update lenders and criteria - `submissions:write` — Submit deals to lenders and withdraw submissions - `offers:read` — Read offers - `offers:write` — Log and update offers, set the primary offer - `advances:read` — Read funded advances and renewal flags - `advances:write` — Update advances - `portal:send` — Generate and send merchant portal links - `webhooks:manage` — Manage webhook subscriptions version: '1.0' contact: {} servers: - url: https://api.nextlevelmca.com description: Production security: - bearer: [] tags: - name: Businesses description: Merchant businesses and their notes, tasks and activity - name: People description: Contacts and owners. Phone lookups normalise to E.164. - name: Deals description: Deals, stage moves, renewals and the pipeline - name: Documents description: Documents, presigned uploads, document requests and statement analysis - name: Lenders description: Lenders and their criteria - name: Lender matches description: Criteria-driven lender matching for a deal - name: Submissions description: Sending deals to lenders - name: Offers description: Lender offers and the primary offer - name: Advances description: Funded advances and renewal readiness - name: Merchant portal description: Magic links for the merchant portal - name: Webhooks description: Outbound event subscriptions paths: /v1/webhooks: post: tags: - Webhooks summary: Create a webhook subscription description: >- Registers an HTTPS endpoint and returns the signing `secret` **once**. **Delivery.** Each event is a `POST` with a JSON body `{ id, type, created_at, location_id, data }` and the headers `Content-Type: application/json`, `User-Agent: NextLevelMCA-Webhooks/1.0`, `X-NLMCA-Event` (the type), `X-NLMCA-Delivery` (unique per attempt group — use it to de-duplicate) and `X-NLMCA-Signature: t=,v1=`. **Verification.** Compute `HMAC-SHA256(secret, t + "." + rawBody)` over the raw request body (before JSON parsing), compare it to `v1` in constant time, and reject when `t` is more than 5 minutes from your clock. Example (Node): `crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")`. **Retries.** Answer 2xx within 10 seconds. Any other response, a redirect or a timeout is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then the delivery is marked dead (replayable from Settings → Developers). Deliveries are at-least-once and may arrive out of order. **Disabling.** A subscription that has failed continuously for 3 days is set to `disabled` and the location admins are emailed. Fix the endpoint, then re-enable it from Settings → Developers → Webhooks. `POST /v1/webhooks/{id}/test` checks an endpoint without waiting for a real event. operationId: webhooks_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookDto' responses: '201': description: Created. `data.secret` is shown only in this response. content: application/json: schema: type: object required: - data - meta properties: data: $ref: '#/components/schemas/WebhookWithSecretDto' meta: $ref: '#/components/schemas/EmptyMetaDto' '400': description: Validation failed. `error.param` names the field. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '401': description: Missing, invalid, expired or revoked credential. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '403': description: Credential lacks the scope, or the role lacks the permission. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '409': description: Conflict (duplicate or idempotency key reuse). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '429': description: Rate limit exceeded. See `X-RateLimit-*` and `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' security: - bearer: [] components: schemas: CreateWebhookDto: type: object properties: url: type: string description: >- Absolute HTTPS endpoint that receives POSTed events. `http://localhost` and `http://127.0.0.1` are accepted for local development only; hosts that resolve to private, loopback or link-local addresses are rejected. example: https://example.com/hooks/nextlevel-mca maxLength: 2048 events: type: array description: >- Event types to deliver. An empty array subscribes to every event, including types added later. example: - deal.created - offer.received - document.uploaded items: type: string enum: - deal.created - deal.stage_changed - deal.funded - deal.dead - submission.sent - submission.responded - offer.received - offer.primary_changed - document.uploaded - document.processed - statement.analyzed - advance.renewal_ready - advance.status_changed - business.created - person.created description: type: string description: >- Label shown in Settings → Developers, e.g. the name of the system that consumes the events. maxLength: 255 example: Zapier — new deals required: - url - events WebhookWithSecretDto: type: object properties: id: type: string description: Subscription id. url: type: string description: Endpoint that receives the events. events: description: Subscribed event types. Empty means every event. type: array items: type: string description: type: string nullable: true description: Label set when the subscription was created. status: type: string enum: - active - disabled description: >- `disabled` after 3 days of continuous failures or when switched off in Settings → Developers. Disabled subscriptions receive nothing until re-enabled there. disabled_reason: type: string nullable: true description: Why the subscription was disabled, when it is. failing_since: type: string nullable: true description: >- When the current run of failures started. `null` while deliveries succeed. last_success_at: type: string nullable: true description: Last time the endpoint answered 2xx. last_failure_at: type: string nullable: true description: Last time a delivery attempt failed. created_at: type: string updated_at: type: string secret: type: string description: >- Signing secret (`whsec_…`). Returned only in this response — store it now. Use it to verify `X-NLMCA-Signature` on every delivery. A new secret can be issued from Settings → Developers. example: whsec_3fK8… required: - id - url - events - description - status - disabled_reason - failing_since - last_success_at - last_failure_at - created_at - updated_at - secret EmptyMetaDto: type: object properties: {} ErrorEnvelopeDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorDto' required: - error PublicErrorDto: type: object properties: type: type: string enum: - validation_error - authentication_error - permission_error - not_found - conflict - rate_limit_error - api_error message: type: string description: Human-readable explanation, safe to show to an operator or an agent. code: type: string description: >- Stable machine-readable code, e.g. `missing_scope`, `duplicate_business`. param: type: string description: Request field the error refers to, when applicable. request_id: type: string description: Echo of the `X-Request-Id` header. Quote it when contacting support. required: - type - message - request_id securitySchemes: bearer: scheme: bearer bearerFormat: API key or JWT type: http description: API key (`nlmca_live_…`) or OAuth access token ```` ## Related topics - [Webhooks](/guides/webhooks.md) - [Get a webhook subscription](/api-reference/webhooks/get-a-webhook-subscription.md) - [List webhook subscriptions](/api-reference/webhooks/list-webhook-subscriptions.md)