API Reference

Create Tax Calculation

Creates a tax calculation for a given set of line items and customer information. The calculation determines applicable tax rates based on the customer's location and can be used to create a transaction after the successful payment.

Request Headers

Request Body Parameters

One endpoint, two product cases: the request shape below covers both digital goods and physical goods with cross-border import duty. Declare the case per line with productType. Worked examples for each case follow the parameter table.

Brazil B2C NFS-e Example

Brazil B2C NFS-e calculations require BRL, customer first and last name, and a BR_CPF tax identifier. In inclusive mode, the submitted line amount remains the service value and ISS tax base; tax is not backed out of the line amount. The response keeps unit price, subtotal, net amount, and total amount at the submitted amount and reports ISS separately.

{
  "currency": "BRL",
  "taxBehavior": "INCLUSIVE",
  "customer": {
    "merchantCustomerReference": "BR-CUST-001",
    "firstName": "Beatriz",
    "lastName": "Costa",
    "email": "beatriz.costa@example.com",
    "taxIdentifiers": [
      {
        "type": "BR_CPF",
        "code": "<VALID_CUSTOMER_CPF>"
      }
    ],
    "billingAddress": {
      "line1": "Rua Oscar Freire, 900",
      "city": "Sao Paulo",
      "state": "SP",
      "postalCode": "01426-002",
      "country": "BR"
    }
  },
  "lineItems": [
    {
      "merchantLineItemReference": "BR-VAS-ITEM-001",
      "productCode": "BR-VAS-001",
      "description": "Value-added mobile service",
      "productType": "DIGITAL",
      "unitPrice": 49.90,
      "quantity": 1
    }
  ],
  "evidence": {
    "billingCountry": "BR",
    "ipAddress": "200.160.2.3",
    "paymentMethodCountry": "BR"
  }
}

{
  "taxCalculationId": "019ef95a-cc77-78da-9041-58908baabaf9",
  "createdAt": "2026-01-05T12:00:00Z",
  "expiresAt": "2026-01-12T12:00:00Z",
  "currency": "BRL",
  "subTotalAmount": "49.90",
  "discountAmount": "0.00",
  "netAmount": "49.90",
  "taxAmount": "1.45",
  "totalAmount": "49.90",
  "customer": {
    "firstName": "Beatriz",
    "lastName": "Costa",
    "email": "beatriz.costa@example.com",
    "billingAddress": {
      "line1": "Rua Oscar Freire, 900",
      "city": "Sao Paulo",
      "state": "SP",
      "postalCode": "01426-002",
      "country": "BR"
    }
  },
  "lineItems": [
    {
      "lineItemId": "83e026ae-b270-4590-926a-03b286fc84d8",
      "merchantLineItemReference": "BR-VAS-ITEM-001",
      "productCode": "BR-VAS-001",
      "description": "Value-added mobile service",
      "unitPrice": "49.90",
      "quantity": 1,
      "discountAmount": "0.00",
      "itemSubTotalAmount": "49.90",
      "itemNetAmount": "49.90",
      "itemTotalAmount": "49.90",
      "tax": {
        "rate": "2.90",
        "taxAmount": "1.45",
        "currency": "BRL"
      }
    }
  ],
  "evidence": {
    "billingCountry": "BR",
    "ipAddress": "200.160.2.3",
    "paymentMethodCountry": "BR"
  },
  "entity": {
    "companyName": "Outpost Brazil Limitada"
  }
}

Brazil CPF Validation Error

Brazil requires exactly one BR_CPF or BR_CNPJ identifier. Use BR_CPF for B2C and BR_CNPJ for B2B. If no Brazilian identifier is present, if more than one is present, or if the value fails check-digit validation, the calculation request is rejected before tax is calculated.

{
  "code": "invalid_argument",
  "errors": [
    {
      "field": "customer.taxIdentifiers[0].code",
      "message": "must be a valid CPF"
    }
  ]
}

Response Fields

A calculation is valid for 7 days from createdAt. After expiresAt it can no longer be converted into a transaction - create a new one.

Charge Breakdown

Every line item carries a tax.charges array describing the individual jurisdiction-level charges behind the line totals.

Error Responses

Create Tax Transaction

Converts a valid tax calculation into a confirmed tax transaction. This endpoint should be called when an order is finalized/paid. Only call after payment authorization/capture succeeds.

Idempotent by merchantTransactionReference: retrying with the same taxCalculationId and reference returns the already-created transaction with 200 - safe to resend after a timeout or lost response, and no duplicate is recorded. Reusing the reference with a different calculation returns 400 invalid_state.

Request Headers

Request Body

{
  "taxCalculationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "merchantTransactionReference": "ORDER-2026-001234",
  "payment": {
    "processor": "stripe",
    "paymentReference": "ch_3Q1234567890abcdef"
  }
}

Request Body Parameters

Response 200 OK

{
  "transactionId": "e83a9c47-2b5d-4f8a-9c12-3d4e5f6a7b8c",
  "refunded": false,
  "createdAt": "2026-01-05T12:05:00Z",
  "confirmedAt": "2026-01-05T12:05:00Z",
  "currency": "EUR",
  "subTotalAmount": "99.99",
  "discountAmount": "10.00",
  "netAmount": "89.99",
  "taxAmount": "18.90",
  "totalAmount": "108.89",
  "merchantTransactionReference": "ORDER-2026-001234",
  "transactionDate": "2026-01-05T12:05:00Z",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "billingAddress": {
      "line1": "Keizersgracht 123",
      "line2": "Apt 4B",
      "city": "Amsterdam",
      "postalCode": "1015 CJ",
      "country": "NL"
    }
  },
  "payment": {
    "processor": "stripe",
    "paymentReference": "ch_3Q1234567890abcdef"
  },
  "refundsOnTransaction": [],
  "lineItems": [
    {
      "lineItemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "merchantLineItemReference": "ITEM-001",
      "productCode": "TEST-SKU-005",
      "description": "Premium Subscription - Annual",
      "unitPrice": "99.99",
      "quantity": 1,
      "discountAmount": "10.00",
      "itemSubTotalAmount": "99.99",
      "itemNetAmount": "89.99",
      "itemTotalAmount": "108.89",
      "tax": {
        "rate": "21.00",
        "taxAmount": "18.90",
        "currency": "EUR"
      },
      "refunded": false
    }
  ],
  "evidence": {
    "billingCountry": "NL",
    "ipAddress": "185.23.108.42",
    "paymentMethodCountry": "NL"
  }
}

Error Responses

List Tax Transactions

Lists the tax transactions committed on your account, newest first. Results are cursor-paginated, and can be narrowed to a single order with merchantTransactionReference.

Request Headers

Query Parameters

Response 200 OK

{
  "transactions": [
    {
      "transactionId": "e83a9c47-2b5d-4f8a-9c12-3d4e5f6a7b8c",
      "refunded": false,
      "createdAt": "2026-01-05T12:05:00Z",
      "confirmedAt": "2026-01-05T12:05:00Z",
      "currency": "EUR",
      "subTotalAmount": "99.99",
      "discountAmount": "10.00",
      "netAmount": "89.99",
      "taxAmount": "18.90",
      "totalAmount": "108.89",
      "merchantTransactionReference": "ORDER-2026-001234",
      "transactionDate": "2026-01-05T12:05:00Z",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "billingAddress": {
          "line1": "Keizersgracht 123",
          "city": "Amsterdam",
          "postalCode": "1015 CJ",
          "country": "NL"
        }
      },
      "payment": {
        "processor": "stripe",
        "paymentReference": "ch_3Q1234567890abcdef"
      },
      "refundsOnTransaction": [],
      "lineItems": [
        {
          "lineItemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "merchantLineItemReference": "ITEM-001",
          "productCode": "TEST-SKU-005",
          "description": "Premium Subscription - Annual",
          "unitPrice": "99.99",
          "quantity": 1,
          "discountAmount": "10.00",
          "itemSubTotalAmount": "99.99",
          "itemNetAmount": "89.99",
          "itemTotalAmount": "108.89",
          "tax": {
            "rate": "21.00",
            "taxAmount": "18.90",
            "currency": "EUR"
          },
          "refunded": false
        }
      ],
      "evidence": {
        "billingCountry": "NL",
        "ipAddress": "185.23.108.42",
        "paymentMethodCountry": "NL"
      }
    }
  ],
  "nextCursor": "MjAyNi0wMS0wNVQxMjowNTowMFo6ZTgzYTljNDc"
}

Response Fields

Error Responses

Get Tax Transaction

Retrieves the details of an existing tax transaction.

Path Parameters

Response 200 OK

Returns a TaxTransactionResponse object (same structure as Create Tax Transaction response).

Error Responses

Get Transaction Refunds

Retrieves all refunds associated with a transaction.

Path Parameters

Response 200 OK

[
  {
    "refundTransactionId": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
    "merchantRefundReference": "REFUND-2026-000456",
    "refundDate": "2026-01-10T15:30:00Z",
    "refundLineItems": [
      {
        "lineItemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "refundLineItemReference": "REFUND-ITEM-001",
        "refundReason": "Customer requested cancellation",
        "refundItemSubTotalAmount": "99.99",
        "refundItemTotalAmount": "108.89",
        "refundTax": {
          "rate": "21.00",
          "taxAmount": "18.90",
          "currency": "EUR"
        }
      }
    ],
    "createdAt": "2026-01-10T15:30:00Z",
    "currency": "EUR",
    "subTotalAmount": "99.99",
    "taxAmount": "18.90",
    "totalAmount": "108.89"
  }
]

Error Responses

Create Refund Transaction

Creates a refund for one or more line items in an existing transaction.

Each refund line refunds the full remaining amount of the original line by default. To refund only part of a line, set amount on that line - a line may be refunded several times, cumulatively up to its original total. The request-level taxBehavior decides how those amounts are read: EXCLUSIVE (the default) treats them as net of tax, INCLUSIVE as gross including tax. It is ignored for lines without an amount.

Idempotent by merchantRefundReference: retrying with the same reference, transaction, and refund line items returns the already-created refund with 200. Reusing the reference against a different transaction, or with different line items or amounts, returns 400 invalid_state.

Path Parameters

Request Body

{
  "merchantRefundReference": "REFUND-2026-000456",
  "refundDate": "2026-01-10T15:30:00Z",
  "refundLineItems": [
    {
      "lineItemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "refundLineItemReference": "REFUND-ITEM-001",
      "refundReason": "Customer requested cancellation"
    }
  ]
}

Request Body Parameters

Partial Refund Example

Refunds 40.00 net of tax against a line that was originally sold for 99.99. The remaining 59.99 stays refundable under a later refund reference.

{
  "merchantRefundReference": "REFUND-2026-000457",
  "refundDate": "2026-01-12T09:15:00Z",
  "taxBehavior": "EXCLUSIVE",
  "refundLineItems": [
    {
      "lineItemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "refundLineItemReference": "REFUND-ITEM-002",
      "refundReason": "Partial credit for service downtime",
      "amount": "40.00"
    }
  ]
}

Response 200 OK

{
  "refundTransactionId": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
  "merchantRefundReference": "REFUND-2026-000456",
  "refundDate": "2026-01-10T15:30:00Z",
  "refundLineItems": [
    {
      "lineItemId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "refundLineItemReference": "REFUND-ITEM-001",
      "refundReason": "Customer requested cancellation",
      "refundItemSubTotalAmount": "99.99",
      "refundItemTotalAmount": "108.89",
      "refundTax": {
        "rate": "21.00",
        "taxAmount": "18.90",
        "currency": "EUR"
      }
    }
  ],
  "createdAt": "2026-01-10T15:30:00Z",
  "currency": "EUR",
  "subTotalAmount": "99.99",
  "taxAmount": "18.90",
  "totalAmount": "108.89"
}

Error Responses

Import Catalogue Product

Imports a single product variant into your catalogue for tax classification. Each call imports one variant. To model a product that comes in multiple options (size, colour, plan tier), send one request per variant and group them under a shared parent product.

Request Headers

Request Body

{
  "productId": "TSHIRT-001-M",
  "productGroupId": "TSHIRT-001",
  "title": "Classic T-Shirt",
  "requiresShipping": true,
  "taxable": true,
  "description": "100% cotton crew-neck t-shirt",
  "category": "Apparel",
  "imageUrl": "https://cdn.example.com/tshirt-001.png",
  "sku": "TSHIRT-001-M",
  "hsCode": "6109.10",
  "countryOfOrigin": "PT",
  "priceAmount": 24.99,
  "priceCurrency": "USD"
}

Request Body Parameters

Response 201 Created

{
  "productId": "TSHIRT-001-M",
  "productGroupId": "TSHIRT-001",
  "title": "Classic T-Shirt",
  "requiresShipping": true,
  "status": "IMPORTED",
  "approvedTaxCode": null,
  "predictedTaxCode": null
}

Response Fields

Product grouping

Two fields control grouping: productId identifies the variant (the sellable unit), and productGroupId identifies the parent product. There are two ways to structure a product:

• Standalone product - omit productGroupId. The variant becomes its own group and the response returns productGroupId as null. Use this for single-option items such as an eBook or a one-off SKU.
• Multi-variant product - send several requests that share one productGroupId, each with a distinct productId. Every call attaches one variant to the same parent product - for example group TSHIRT-001 with variants TSHIRT-001-S, TSHIRT-001-M and TSHIRT-001-L.

Standalone product example:

{
  "productId": "EBOOK-101",
  "title": "Tax Compliance Handbook (eBook)",
  "requiresShipping": false,
  "priceAmount": 9.99,
  "priceCurrency": "USD"
}

Product-level vs variant-level fields

• Product-level (title, description, category, imageUrl) is keyed by the group. Keep these identical across all variants of one group.
• Variant-level (sku, priceAmount, priceCurrency, taxable, requiresShipping, hsCode, countryOfOrigin) is specific to each variant.

Re-importing

• Re-sending a variant with identical content is a no-op.
• Changing title or description while the variant is APPROVED clears the approval and returns the variant to READY_FOR_CLASSIFICATION for re-review.
• Changing only priceAmount, hsCode or countryOfOrigin updates the variant silently and keeps any approval.
• Importing a new productId under an existing productGroupId adds a variant. Tax codes are not inherited; each variant is classified and approved on its own.

Classification lifecycle

The status field moves through IMPORTED → EXTRACTED → READY_FOR_CLASSIFICATION → APPROVED → ARCHIVED. predictedTaxCode is set by the classifier after import; approvedTaxCode is set when an operator approves. A fresh import returns IMPORTED with both codes null.

Error Responses

Create Proforma Invoice

Requests a proforma invoice for a B2B customer who is paying by bank transfer. A proforma invoice is a non-fiscal request for payment: it states what is owed, to whom, and how to pay, before the money has been received. Issuance is asynchronous - the call returns 202 Accepted with a handle, and Outpost links the tax transaction and renders the PDF afterwards. The document is fetched from its own endpoint once issuance completes.

How it works

• Your checkout collects the B2B customer details, line items, and jurisdiction.
• Your backend calls POST /api/proforma-invoices with that payload and a fresh Idempotency-Key. The call returns 202 Accepted with the id, number, and status PENDING_TAX_TRANSACTION - no document and no amounts.
• Outpost links the tax transaction, renders the PDF, and attaches it. This normally takes seconds.
• Outpost sends proforma_invoice.issued once the document is available, or proforma_invoice.issuance_failed if issuance failed permanently.
• You fetch the PDF from GET /api/proforma-invoices/{id}/document and display or email it to the customer with bank-transfer instructions.
• When the transfer settles, Outpost sends a proforma_invoice.settled webhook so you can fulfill the order.

Waiting for completion

• Register proforma_invoice.issued and proforma_invoice.issuance_failed and treat the webhook as your completion signal.
• Poll GET /api/proforma-invoices/{id} as the fallback, honouring Retry-After. The create response carries Retry-After: 2 and its Location header is the path to poll.
• The create response body is a handle, not a state snapshot: its status is the constant PENDING_TAX_TRANSACTION and never changes. Only the poll reports current state.
• PENDING_TAX_TRANSACTION normally lasts seconds, so a short backoff is enough.

Request Headers

Request Body Parameters

Response 202 Accepted

{
  "id": "7b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "number": "10026-OP-001",
  "status": "PENDING_TAX_TRANSACTION",
  "merchantReference": "order-1042"
}

Response Headers

Response Fields

Error Responses

Idempotency

Create is idempotent on the Idempotency-Key header, so a retried or duplicated submission can never produce two proforma invoices for the same order.

Rules

• Send an Idempotency-Key on every create. The header is required and may be at most 255 characters.
• Same key, same body - the original handle is replayed. No second proforma invoice is created.
• Same key, different body - the request is rejected with 422 idempotency_key_reused. Nothing is created.
• Generate the key per submission attempt. Never derive it from the document contents, and never reuse it for a different document.
• A replay always returns status PENDING_TAX_TRANSACTION, even when the proforma invoice has long since been issued or failed. Poll GET /api/proforma-invoices/{id} for current state.
• A spent key replays its proforma invoice handle forever, including after that proforma invoice has been deleted. Recreating after a delete needs a new key.

Replacing a proforma invoice

A proforma invoice that has not been issued yet can be deleted and recreated under the same merchantReference, which is how you correct a mistake before the customer ever sees the document.

• DELETE /api/proforma-invoices/{id} - 204. The proforma invoice disappears from all reads and releases its merchantReference.
• POST /api/proforma-invoices with the corrected body, the same merchantReference, and a NEW Idempotency-Key.
• Reusing the old key here replays the deleted proforma invoice handle instead of creating the replacement.

Error envelope

Every error on this resource shares one shape: a machine-readable code and an errors list of field-level messages.

{
  "code": "proforma_tax_input_invalid",
  "errors": [
    { "field": "recipient", "message": "Recipient is required" }
  ]
}

merchant_reference_conflict adds a top-level existingProformaInvoiceId naming the live proforma invoice that holds the reference.

{
  "code": "merchant_reference_conflict",
  "existingProformaInvoiceId": "019d4d40-15cf-7764-ad6e-b2ec47736bb9",
  "errors": [
    { "field": "merchantReference", "message": "merchantReference is already in use" }
  ]
}

Status Lifecycle

Every proforma invoice starts at PENDING_TAX_TRANSACTION and either reaches ISSUED or ends at the terminal ISSUANCE_FAILED. Read the current status from GET /api/proforma-invoices/{id} - never from the create response.

Get Proforma Invoice

Returns the proforma invoice. This is the poll target named by the create response’s Location header and the only authority on current state. It answers 200 OK at every stage of the lifecycle, including PENDING_TAX_TRANSACTION and ISSUANCE_FAILED.

Request Headers

Path Parameters

Response 200 OK

{
  "id": "7b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "number": "10026-OP-001",
  "status": "ISSUED",
  "merchantReference": "order-1042"
}

Response 200 OK - issuance failed

A permanent failure is still a 200. The failure detail lives in issuanceFailure.

{
  "id": "7b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "number": "10026-OP-001",
  "status": "ISSUANCE_FAILED",
  "merchantReference": "order-1042",
  "issuanceFailure": {
    "code": "proforma_tax_input_invalid",
    "message": "Recipient is required",
    "failedAt": "2026-09-08T12:00:00Z"
  }
}

Response Fields

Error Responses

Get Proforma Invoice Document

Returns a pre-signed link to the proforma invoice PDF. The link is valid for 15 minutes and the endpoint may be called any number of times, so fetch a fresh link whenever you need to show or send the document rather than storing the URL.

Request Headers

Path Parameters

Response 200 OK

{
  "fileName": "proforma-invoice-10026-OP-001.pdf",
  "url": "https://storage.outpostanywhere.com/proforma-invoices/7b1f2c3d-...pdf",
  "expiresAt": "2026-09-08T12:15:00Z"
}

Response Fields

Error Responses

Delete Proforma Invoice

Deletes a proforma invoice that has not been issued yet. Use it to withdraw a submission you got wrong, then create the replacement under the same merchantReference.

Request Headers

Path Parameters

Behaviour

• Deletion is allowed until the tax transaction is linked. After that the endpoint returns 409 not_deletable and the proforma invoice must be cancelled instead.
• Deleting an already-deleted proforma invoice returns 204 as well - the call is idempotent.
• Deletion is soft on Outpost’s side and permanent from yours: the proforma invoice disappears from every read, its document is no longer retrievable, and it never comes back.
• A deleted proforma invoice releases its merchantReference, so a fresh create may reuse it. merchant_reference_conflict therefore only ever names a live proforma invoice.

Error Responses

Get Payment Invoice by ID

Retrieves the B2C tax invoice for a payment using the Outpost payment ID.

Request Headers

Path Parameters

Response 200 OK

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Response Fields

Error Responses

Get Payment Invoice by PSP Reference

Retrieves the B2C tax invoice for a payment using the PSP reference (e.g., Adyen pspReference or Stripe charge ID).

Request Headers

Query Parameters

Response 200 OK

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Error Responses

Get Refund Invoice by ID

Retrieves the B2C tax invoice for a refund using the Outpost refund ID.

Request Headers

Path Parameters

Response 200 OK

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Error Responses

Get Refund Invoice by PSP Reference

Retrieves the B2C tax invoice for a refund using the PSP reference.

Request Headers

Query Parameters

Response 200 OK

{
  "invoice": {
    "fileName": "invoice-7110000000023059375.pdf",
    "url": "https://storage.outpostanywhere.com/invoices/...",
    "expiresAt": "2026-01-05T12:15:00Z"
  }
}

Error Responses

Register Webhook

Registers an endpoint to receive event notifications. The response includes a secret that is shown only once - store it to verify incoming signatures.

Request Headers

Request Body Parameters

Response 201 Created

{
  "id": "wh_019d4d40-15cf-7764-ad6e-b2ec47736bb9",
  "url": "https://your-app.example.com/webhooks/outpost",
  "events": ["proforma_invoice.settled"],
  "secret": "whsec_8f2b...d41a",
  "status": "ACTIVE",
  "createdAt": "2026-06-01T12:00:00Z"
}

Response Fields

Error Responses

List Webhooks

Returns all webhook endpoints registered for your merchant account.

Response 200 OK

[
  {
    "id": "wh_019d4d40-15cf-7764-ad6e-b2ec47736bb9",
    "url": "https://your-app.example.com/webhooks/outpost",
    "events": ["proforma_invoice.settled"],
    "status": "ACTIVE",
    "createdAt": "2026-06-01T12:00:00Z"
  }
]

Delete Webhook

Removes a webhook endpoint. It immediately stops receiving events.

Path Parameters

Error Responses

Webhook events

Each subscribed event is delivered as an HTTP POST to your endpoint with a JSON body.

Delivery Semantics

• Acknowledge a delivery with any 2xx status. Each attempt has 30 seconds to respond.
• A 429 or 5xx response is retried. Any other 4xx response is a permanent failure and stops delivery of that event.
• Retries use exponential backoff: at most 8 attempts, the first 10 seconds after the failure, tripling each time, capped at 4 hours between attempts and 9 hours in total.
• Deliveries are at-least-once - deduplicate on the full event id.
• The event id is deterministic per entity and topic, so a redelivered event always carries the same id, and two topics about the same entity never collide.
• Always verify the Outpost-Signature header before acting on a payload.

Verifying Signature

Every delivery includes an Outpost-Signature header of the form t=<timestamp>,v1=<hmac>. Compute an HMAC-SHA256 of {t}.{rawBody} with your webhook secret and compare it against v1 in constant time. Reject requests whose timestamp is older than five minutes to prevent replay.

// Verify the Outpost-Signature header before trusting the payload
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

boolean verify(String rawBody, String header, String secret) throws Exception {
  // header looks like: t=1717243200,v1=5257a869e7...
  Map<String, String> parts = parseHeader(header);
  String signedPayload = parts.get("t") + "." + rawBody;

  Mac mac = Mac.getInstance("HmacSHA256");
  mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
  byte[] digest = mac.doFinal(signedPayload.getBytes());
  String expected = HexFormat.of().formatHex(digest);

  return MessageDigest.isEqual(expected.getBytes(), parts.get("v1").getBytes());
}

Events

Common fields

Every event shares these top-level fields. Event-specific fields live inside data.