Boarding Webhooks | Run Developers

Boarding webhooks notify you about merchant onboarding status changes and specific boarding process events.

Event Context: `trigger` and `reason`

Every merchant.* payload carries two fields describing how and why the change happened. The event type tells you the state the merchant is now in; these tell you what caused it.

Field	Values
`trigger`	`api` — a Boarding API call · `ui` — someone acting in Run Partner · `system` — an automated process
`reason`	the business action, listed below

Why this matters

Four different things can produce a merchant.new event:

What happened	`trigger`	`reason`
A rep clicked Recall Signature Request in Run Partner	`ui`	`retracted`
An API caller sent `PUT /merchants/{merchant_id}` with `merchant_status: "new"`	`api`	`retracted`
An API caller updated an application that was out for signature	`api`	`updated`
Our 30-day sweep expired an unsigned application	`system`	`signature_expired`

Previously all four arrived as an indistinguishable merchant.new. If your integration takes action on merchant.new — creating a record, notifying a team — branch on reason rather than treating every occurrence as a brand-new application.

`reason` values

created · sent_for_signature · resent · retracted · updated · signed · in_underwriting · boarded · live · cancelled · declined · signature_expired · deleted · status_changed

Treat reason as open-ended, not a fixed enum. status_changed is a fallback for transitions with no more specific meaning, and new values may be added over time. Ignore a value you do not recognise rather than failing on it.

Resending emits a single event

Re-sending an application that is already out for signature retracts the outstanding link and issues a fresh one. That produces one event — merchant.sent_for_signature with reason: resent — not a merchant.new followed by a merchant.sent_for_signature.

A first send from new also produces one merchant.sent_for_signature, with reason: sent_for_signature. So the event type is the same either way, and reason tells you whether a previous link was replaced.

There is no way to suppress webhooks for an individual request. The event stream is the record of what happened, so silencing it for one caller would leave other subscribers out of sync. Use trigger and reason to decide which events your integration should act on.

Merchant Status Events

The following webhooks are triggered when a merchant’s status changes during the boarding process. Each payload also carries trigger and reason — see Event Context above.

`merchant.new`

Triggered when merchant status changes to “New”.

{
  "event_type": "merchant.new",
  "source_id": "88001",
  "timestamp": "2025-09-11T15:30:45.123Z",
  "payload": {
    "merchant_id": 88001,
    "mid": null,
    "rep_code_id": 7105,
    "customer_id": 88001,
    "dba_name": "New Business Venture",
    "merchant_status_id": 1,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "api",
    "reason": "created",
    "timestamp": "2025-09-11T15:30:45.100+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562401",
    "attempt": 1,
    "idempotency_key": "a1b2c3d4e5f6789012345678901234567890abcd"
  }
}

`merchant.sent_for_signature`

Triggered when merchant status changes to “Sent For Signature”.

{
  "event_type": "merchant.sent_for_signature",
  "source_id": "91569",
  "timestamp": "2025-09-11T19:42:24.438Z",
  "payload": {
    "merchant_id": 91569,
    "mid": null,
    "rep_code_id": 7107,
    "customer_id": 88005,
    "dba_name": "The Bagel Shop - Breckenridge",
    "merchant_status_id": 2,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "api",
    "reason": "sent_for_signature",
    "timestamp": "2025-09-11T19:42:24.420+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562459",
    "attempt": 1,
    "idempotency_key": "97667363c9d970ba458dc90c1e92a374"
  }
}

`merchant.signed`

Triggered when merchant status changes to “Signed”.

{
  "event_type": "merchant.signed",
  "source_id": "88003",
  "timestamp": "2025-09-12T08:15:30.456Z",
  "payload": {
    "merchant_id": 88003,
    "mid": null,
    "rep_code_id": 7107,
    "customer_id": 88003,
    "dba_name": "Downtown Coffee Shop",
    "merchant_status_id": 3,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "ui",
    "reason": "signed",
    "timestamp": "2025-09-12T08:15:30.420+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562461",
    "attempt": 1,
    "idempotency_key": "b2c3d4e5f6789012345678901234567890abcde"
  }
}

`merchant.in_underwriting`

Triggered when merchant status changes to “In Underwriting”.

{
  "event_type": "merchant.in_underwriting",
  "source_id": "88004",
  "timestamp": "2025-09-12T14:20:15.789Z",
  "payload": {
    "merchant_id": 88004,
    "mid": null,
    "rep_code_id": 7108,
    "customer_id": 88004,
    "dba_name": "Mountain View Restaurant",
    "merchant_status_id": 4,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "system",
    "reason": "in_underwriting",
    "timestamp": "2025-09-12T14:20:15.750+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562475",
    "attempt": 1,
    "idempotency_key": "c3d4e5f6789012345678901234567890abcdef"
  }
}

`merchant.boarded`

Triggered when merchant status changes to “Boarded”.

{
  "event_type": "merchant.boarded",
  "source_id": "88006",
  "timestamp": "2025-09-13T10:45:22.334Z",
  "payload": {
    "merchant_id": 88006,
    "mid": "496581123456789",
    "rep_code_id": 7109,
    "customer_id": 88006,
    "dba_name": "Tech Solutions Inc",
    "merchant_status_id": 5,
    "external_crm_id": "CRM-2025-001",
    "custom_01": "APPROVED",
    "trigger": "system",
    "reason": "boarded",
    "timestamp": "2025-09-13T10:45:22.300+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562490",
    "attempt": 1,
    "idempotency_key": "d4e5f6789012345678901234567890abcdef01"
  }
}

`merchant.live`

Triggered when merchant status changes to “Live”.

{
  "event_type": "merchant.live",
  "source_id": "88007",
  "timestamp": "2025-09-13T16:20:33.567Z",
  "payload": {
    "merchant_id": 88007,
    "mid": "496581987654321",
    "rep_code_id": 7110,
    "customer_id": 88007,
    "dba_name": "Online Retail Store",
    "merchant_status_id": 6,
    "external_crm_id": "CRM-2025-002",
    "custom_01": "LIVE",
    "trigger": "system",
    "reason": "live",
    "timestamp": "2025-09-13T16:20:33.520+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562510",
    "attempt": 1,
    "idempotency_key": "e5f6789012345678901234567890abcdef0123"
  }
}

`merchant.cancelled`

Triggered when merchant status changes to “Cancelled”.

{
  "event_type": "merchant.cancelled",
  "source_id": "88008",
  "timestamp": "2025-09-13T11:30:45.234Z",
  "payload": {
    "merchant_id": 88008,
    "mid": null,
    "rep_code_id": 7111,
    "customer_id": 88008,
    "dba_name": "Cancelled Business",
    "merchant_status_id": 7,
    "external_crm_id": null,
    "custom_01": "CANCELLED",
    "trigger": "ui",
    "reason": "cancelled",
    "timestamp": "2025-09-13T11:30:45.200+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562520",
    "attempt": 1,
    "idempotency_key": "f6789012345678901234567890abcdef012345"
  }
}

`merchant.declined`

Triggered when merchant status changes to “Declined”.

{
  "event_type": "merchant.declined",
  "source_id": "88009",
  "timestamp": "2025-09-13T13:15:22.890Z",
  "payload": {
    "merchant_id": 88009,
    "mid": null,
    "rep_code_id": 7112,
    "customer_id": 88009,
    "dba_name": "High Risk Venture",
    "merchant_status_id": 8,
    "external_crm_id": "CRM-2025-DECLINED",
    "custom_01": "DECLINED",
    "trigger": "ui",
    "reason": "declined",
    "timestamp": "2025-09-13T13:15:22.850+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562530",
    "attempt": 1,
    "idempotency_key": "g789012345678901234567890abcdef0123456"
  }
}

`merchant.unknown`

Triggered when merchant status changes to “Unknown”.

{
  "event_type": "merchant.unknown",
  "source_id": "88010",
  "timestamp": "2025-09-13T09:45:11.123Z",
  "payload": {
    "merchant_id": 88010,
    "mid": null,
    "rep_code_id": 7113,
    "customer_id": 88010,
    "dba_name": "Status Unknown Business",
    "merchant_status_id": 9,
    "external_crm_id": null,
    "custom_01": "ERROR",
    "trigger": "system",
    "reason": "status_changed",
    "timestamp": "2025-09-13T09:45:11.100+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562540",
    "attempt": 1,
    "idempotency_key": "h89012345678901234567890abcdef01234567"
  }
}

`merchant.deleted`

Triggered when merchant record is deleted from Partner.

{
  "event_type": "merchant.deleted",
  "source_id": "102398",
  "timestamp": "2026-01-07T04:11:13.499Z",
  "payload": {
    "merchant_id": 102398,
    "mid": null,
    "rep_code_id": 13308,
    "customer_id": 99092,
    "dba_name": "Test Merchant",
    "merchant_status_id": 1,
    "external_crm_id": "external 100010",
    "custom_01": "custom01222",
    "deleted_by": "integrations@runpayments.io",
    "trigger": "ui",
    "reason": "deleted",
    "timestamp": "2026-01-07T04:10:38.170+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562934",
    "attempt": 1,
    "idempotency_key": "5c672af3e79155fcaf7dbae89279c294"
  }
}

VAR Complete Event

`boarding.varcomplete`

Triggered when the TSYS VAR Only process is complete.

{
  "event_type": "boarding.varcomplete",
  "source_id": "12345",
  "timestamp": "2024-01-17T15:30:00.000Z",
  "payload": {
    "merchant_id": "88001",
    "acquirer_bin": "496581",
    "agent_bank_number": "000001",
    "agent_chain_number": "111111",
    "city": "Commerce City",
    "zip_code": "90210",
    "contact_phone": "5551234567",
    "merchant_aba_number": "123456789",
    "merchant_category_code": "5812",
    "merchant_location_number": "00001",
    "dba_name": "Acme Store",
    "mid": "496581000123456",
    "merchant_settlement_agent_number": "A001",
    "state": "CA",
    "store_number": "0001",
    "terminal_id": "T001ABC",
    "terminal_number": "0001",
    "time_zone": "America/Los_Angeles"
  },
  "metadata": {
    "webhook_id": "wh_var_001",
    "attempt": 1,
    "idempotency_key": "boarding-varcomplete-12345-20240117153000"
  }
}

Integration Tips

Status Tracking: Maintain merchant status in your system based on webhook events
Automated Communications: Send status updates and next steps to merchants automatically
Team Notifications: Alert sales and support teams about status changes

Error Handling

Handle potential issues in boarding webhooks:

Missing Data: Some optional fields may be null depending on application completeness
Status Transitions: Ensure your system can handle status changes in any order
Duplicate Events: Use idempotency keys to prevent duplicate processing

Event Context: trigger and reason

Why this matters

reason values

Resending emits a single event

Merchant Status Events

merchant.new

merchant.sent_for_signature

merchant.signed

merchant.in_underwriting

merchant.boarded

merchant.live

merchant.cancelled

merchant.declined

merchant.unknown

merchant.deleted