Skip to content
MothershipDevelopers

Webhook eventsInvoices

Invoice created

Sent when an invoice is issued to your organization.

EVENTinvoice.created
POST to your endpointSigned with HMAC-SHA256Retried for up to 4 daysPermission to read invoices
RequestPOSThttps://your-server.example.com/webhooks/mothership
Content-Type:application/json
X-Mothership-Signature:4c51d8eb305041994005bfcf8a9f97641dcabdee4ffbe33bb77718abddb55180
X-Mothership-Delivery-Id:3f6c1a9e-8b2d-4c7a-9e15-2d8b7f4a6c01
{
: "invoice.created",
: {
: {
: "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
: "MSI123456",
: "open",
: "shipment",
: "MS123456",
: 42500,
: 42500,
: "usd",
: "2026-11-07T15:04:05.000Z",
: "2026-10-08T15:04:05.000Z",
: "2026-10-08T15:04:05.000Z"
}
},
: "2026-10-08T15:04:05.000Z",
: 1,
: 16
}

Hover a key to see what it means. Click it to jump to the field.

Sent when an invoice is issued to your organization. Drafts stay hidden, so an invoice that starts as a draft sends this when it leaves draft. An invoice already paid when it is issued sends invoice.paid right after.

A new invoice sends invoice.created alone, even when its line items arrive a moment later. An invoice voided in the seconds before its invoice.created would go out sends nothing.

Subscribing

Add invoice.created to a configuration's subscribedEvents with Create a webhook configuration or in the dashboard. The token needs permission to read invoices. Without it, the request answers 403 MISSING_PERMISSION, and opening or resending these deliveries in the dashboard is refused too. Such a token can still remove the event from a configuration.

Event data

data · 1 keys
  • invoiceobject

    The invoice as it is when Mothership sends the event, named as Retrieve an invoice names it. Call that with invoice.id for line items, payments and credits.

Envelope

Same on every event
  • eventTypestring

    The event. Always invoice.created here. Route on it, and answer 2xx to types you don't handle.

  • sentAtstring

    When Mothership queued the event to send, as an ISO 8601 string in UTC. Every retry and resend carries the same value, so it does not say when this attempt went out.

  • deliveryAttemptinteger

    Which send of this event this is, starting at 1. Resends from the dashboard count too.

  • pendingRetriesinteger

    How many automatic attempts are left if this one fails. 0 on the last one.

Related

invoice.updatedSent when anything on an invoice changes, such as a line item, a payment, a credit or its status.invoice.paidSent when an invoice is paid in full.Receiving webhooksVerify the signature, answer within 30 seconds, and handle retries and duplicates.