- Webhooks
- Webhooks
Webhooks
Webhooks
Receive signed real-time HTTP callbacks for events in your Remitian integration.
Webhooks let your systems receive real-time HTTP callbacks when events occur in your Remitian integration — no polling required. Events are delivered as signed JSON payloads to a single endpoint URL that you manage from the Developer Portal.
Managing Webhooks in the Developer Portal
Everything about your webhook subscription is self-service in the portal’s Webhooks section (Editor role required to make changes):
- Endpoint URL — a single HTTPS URL that receives all subscribed events
- Supported Events — choose exactly which event types you want to receive
- Signature Token — the secret used to sign every delivery; view, copy, or regenerate it at any time
- Max Delivery Attempts — how many times a failed delivery is retried (1–10, default 3)
- Activate / Deactivate — turn delivery on or off without losing your configuration
- Send Test Event — deliver a
webhook.Test.v1event to verify your endpoint end-to-end
Start Receiving Events
- Expose an HTTPS endpoint in your system that accepts
POSTrequests with a JSON body. - In the Developer Portal, open Webhooks and choose Set up webhooks.
- Enter your endpoint URL and save.
- Select the event types you want to receive.
- Copy the signature token and implement signature verification (see Verifying Signatures below).
- Activate the configuration (activation requires a saved endpoint URL).
- Click Send test event and confirm your endpoint receives and verifies a
webhook.Test.v1delivery.
Note: Regenerating the signature token invalidates the previous one immediately — deliveries signed with the new token will fail verification in systems still using the old value.
Event Envelope
Every delivery is a POST request with Content-Type: application/json. The body is a common envelope; the data field carries the event-specific payload. Property names are camelCase and enum values are serialized as strings.
{
"id": "019b2a7f-1c34-7e90-8a2b-0f5d6c1e3a42",
"eventType": "schedule.Processed.v1",
"createdAtUtc": "2026-07-24T17:00:00Z",
"data": {
"id": "019b2952-c553-7a93-ba57-d3baf8e09cb0",
"firm": {
"id": "019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10",
"externalId": "FIRM-1042"
},
"taxpayerId": "019bc3f4-d65e-73f7-8133-f5800e825509",
"status": "Processed",
"confirmationNumber": "2026072400123456",
"currency": "USD",
"amount": 1250.00
}
}
| Field | Description |
|---|---|
id | Unique identifier of this delivery: a UUID serialized as a canonical hyphenated lowercase 36-character string. Treat it as an opaque unique key and use it for idempotency: the same event is never delivered with two different ids, but the same id may be retried. |
eventType | The topic name (see Event Types and Payloads). The .vN suffix versions the payload schema. |
createdAtUtc | When the event was created (UTC, ISO-8601). |
data | The event payload. Schema depends on the event type family. |
Available Event Types
Events are grouped in families. Each family shares one payload schema.
| Family | Event Types | Sent when |
|---|---|---|
| Test | webhook.Test.v1 | You press Send test event in the Developer Portal |
| Tax Payments | schedule.* | A tax payment changes status |
| Tax Form Imports | taxFormParsingRequest.* | A tax form parsing request changes status |
| Batches | batch.* | Every item of a batch has succeeded or failed |
| SFTP File Delivery | outboundFile.* | An outbound file is published and ready to download |
| Tax Identity Verifications | taxIdentityVerification.* | A tax identity verification is created, succeeds or fails |
See Event Types and Payloads for every event type, the payload fields and examples.
Verifying Signatures
Every delivery includes a payload-signature header so you can verify it originated from Remitian and was not tampered with.
- Algorithm: HMAC-SHA256 over the raw request body
- Key: your configuration’s signature token (as its string value, from the Developer Portal)
- Encoding: Base64
Example (Node.js):
const crypto = require("crypto");
function verifySignature(rawBody, signatureHeader, signatureToken) {
const expected = crypto
.createHmac("sha256", signatureToken)
.update(rawBody, "utf8")
.digest("base64");
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader)
);
}
Important: Compute the HMAC over the raw body exactly as received, before any JSON parsing or re-serialization.
Delivery, Timeouts, and Retries
- Your endpoint must respond with a 2xx status code within 30 seconds for the delivery to be considered successful.
- Any non-2xx response, timeout, or connection error counts as a failed attempt.
- Failed deliveries are retried with exponential backoff: 30 seconds after the first failure, doubling each attempt (30s, 1m, 2m, 4m, 8m…), capped at 15 minutes between attempts.
- Retries stop after your configured Max Delivery Attempts (1–10, default 3); the delivery is then marked permanently failed.
Best Practices
- Respond fast: acknowledge with a 2xx immediately and process the event asynchronously.
- Be idempotent: deduplicate on the envelope
id— retries reuse the same id. - Don’t rely on ordering: events may arrive out of order; use
createdAtUtcand your own state to reconcile. - Protect the signature token: treat it like any other secret and rotate it periodically.
Source IP Addresses
Webhook deliveries are sent from static IP addresses. If your firewall restricts inbound traffic, allow these addresses to reach your endpoint URL:
| Region | Sandbox | Production |
|---|---|---|
| United States | 3.215.17.149 | 44.216.157.23444.217.164.59 |
| Canada | 99.79.98.154 | 3.99.254.8035.183.201.179 |
- Static. These addresses do not change.
- Outbound only. Remitian uses them only to send webhook deliveries. Do not use them to reach Remitian.
- Use the addresses of your region. Deliveries come from the region of your account. See Base URLs by Region.
- Allow every address of the environment. A Production delivery can come from either of its two addresses.
- Keep verifying signatures. An IP allowlist does not replace the
payload-signaturecheck.
Need Help?
- Email: support@remitian.com
- Response Time: Within 1-2 business days