WEBHOOKS

Set the webhook endpoint

POSThttps://production.dutchapi.co/v1/webhooks

Registers (or replaces) your single webhook URL and returns a new signing secret, shown once.

🔒Send the project API key as a Bearer token and your Business ID with this call.

Events: collection.received, collection.failed, payout.completed, payout.failed, deposit.received, exchange.completed, exchange.failed, card.issued, card.funded, card.withdrawn, card.funding_failed, card.transaction, card.refund. See Webhooks for each payload.

Each delivery carries X-Dutch-Event and X-Dutch-Signature: t=<unix>,v1=<hex> where v1 is HMAC-SHA256 of <t>.<raw body> with your signing secret. Reject deliveries older than 5 minutes.

In production the URL must be public https.

Body Params

urlstringrequired

Your https endpoint.

Responses

{
  "url": "https://example.com/webhooks/dutch",
  "signing_secret": "whsec_...",
  "events": [
    "collection.received",
    "collection.failed",
    "payout.completed",
    "payout.failed",
    "deposit.received",
    "exchange.completed",
    "exchange.failed",
    "card.issued",
    "card.funded",
    "card.withdrawn",
    "card.funding_failed",
    "card.transaction",
    "card.refund"
  ]
}

{
  "error": "invalid_webhook_url",
  "message": "The URL is not acceptable."
}

Errors

Status	error	Meaning
400	`invalid_webhook_url`	The URL is not acceptable.

Updated 2026

Did this page help you?

PreviousList transactions NextGet the webhook endpoint

Language

CredentialsBearer

curl --request POST --url "https://production.dutchapi.co/v1/webhooks" \
  --header "Authorization: Bearer $DUTCH_PROJECT_KEY" \
  --header "X-Business-Id: $DUTCH_BUSINESS_ID" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com/webhooks/dutch"}'

const res = await fetch("https://production.dutchapi.co/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.DUTCH_PROJECT_KEY,
    "X-Business-Id": process.env.DUTCH_BUSINESS_ID,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"url": "https://example.com/webhooks/dutch"})
});
console.log(await res.json());

require "net/http"
require "json"

uri = URI("https://production.dutchapi.co/v1/webhooks")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('DUTCH_PROJECT_KEY')}"
req["X-Business-Id"] = ENV.fetch("DUTCH_BUSINESS_ID")
req["Content-Type"] = "application/json"
req.body = "{\"url\":\"https://example.com/webhooks/dutch\"}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

<?php
$ch = curl_init("https://production.dutchapi.co/v1/webhooks");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("DUTCH_PROJECT_KEY"),
    "X-Business-Id: " . getenv("DUTCH_BUSINESS_ID"),
    "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"url":"https://example.com/webhooks/dutch"}',
]);
echo curl_exec($ch);

import os, requests, json

res = requests.request(
    "POST",
    "https://production.dutchapi.co/v1/webhooks",
    headers={
        "Authorization": "Bearer " + os.environ["DUTCH_PROJECT_KEY"],
        "X-Business-Id": os.environ["DUTCH_BUSINESS_ID"],
    },
    json=json.loads("{\"url\":\"https://example.com/webhooks/dutch\"}")
)
print(res.json())

Response

Click `Show example` to see an example response. Nothing is sent from this page: endpoints are live, so run real requests from your own code with small amounts.