Create a webhook

Requires the client/write scope. Authenticated the same way as every other endpoint — the same Authorization: Bearer <access token> + x-client-id pair, there is no separate webhook credential.

Delivery is via AWS SNS HTTPS subscription: after creating the subscription your endpoint receives an SNS SubscriptionConfirmation message that must be confirmed before notifications flow — no events are delivered until that handshake is actioned.

Kobble appends a ?client-id=<your client id> query parameter to the subscription URL at creation (visible on the stored url); your endpoint receives it on every delivery. Any load balancer, API gateway or router in front of your endpoint must forward the query string unchanged, or deliveries will arrive without it.

One subscription receives ALL event types for your client — there is no per-event-type filtering. Webhooks are zero-trust notifications: payloads carry identifiers and the event type, never resource state — always re-fetch the resource. Deduplicate on (entity_id, type): an SNS redelivery reuses the same notification id, but an upstream replay of the same event generates a new one.

Verify every delivery before you act on it. Check the SNS signature against the certificate named by SigningCertURL, having first confirmed that URL is an https host under amazonaws.com; never fetch an arbitrary URL taken from the payload. Then compare the envelope's TopicArn against the per-environment topic ARN Kobble issues you at onboarding. The signature alone proves only that a message originated from AWS, not that it originated from Kobble, so an endpoint that checks the signature but not the topic will accept any signed SNS message from any AWS account.

There is no settlement event. Settlement and settlement reversal are internal transaction types excluded from delivery, so you will never receive one and should not wait for one. A payout has settled once its transaction reaches ACCEPTED and transaction-accept is delivered. A dishonour after settlement arrives as a new REFUND transaction carrying the original transaction's id in external_id, while the original stays ACCEPTED — a reversal can never be detected by watching the original transaction's status.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Bodyapplication/json

Example

{
    "id": "530d8eae-b44c-4ae3-9c31-874bf98b2bdf",
    "owner": "a30595d9-de0a-42ae-b3f3-55643abd2eb8",
    "url": "https://male-goat.biz?client-id=a30595d9-de0a-42ae-b3f3-55643abd2eb8",
    "created_at": "2025-01-14T17:00:33.406Z",
    "updated_at": "2025-01-14T17:00:33.410Z",
    "metadata": {
        "subscription_arn": "arn:aws:sns:ap-southeast-2:123456789012:webhooks-topic:530d8eae-b44c-4ae3-9c31-874bf98b2bdf"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden