Skip to main content
POST
Create Webhook Endpoint
Registers a URL that Hop posts events to, and returns the signing secret for that endpoint. Requires write access on the webhooks scope. The secret is returned only in this response and is never shown again. Store it before you discard the response; if you lose it, delete the endpoint and create a new one. This endpoint does not take an Idempotency-Key. A retried request creates a second endpoint with its own secret, and both endpoints then receive every event they subscribe to.

Path Parameters

string
required
The customer’s external ID (starts with cus_)

Request Body

string
required
The URL events are posted to. Must use https and include a host; http URLs are rejected. Normalised before storage, so a bare host gains a trailing slash and https://api.example.com comes back as https://api.example.com/: compare against the url in the response, not the string you sent, and expect the normalised form if your receiver checks the request path.
array
required
Event types to subscribe to. At least one is required, and each must be one of:payin.received, payin.returned, payout.created, payout.completed, payout.failed, transfer.completed, transfer.failed, account.created, account.updated, payout_destination.updatedAny other name is rejected. See Webhook Events for what each one carries.
string
Optional description for the endpoint (maximum 255 characters)

Response

string
Webhook endpoint identifier (starts with wh_)
string
Always returns "webhook_endpoint"
string
The stored delivery URL, after normalisation
array
Subscribed event types
string
The description, or null
string
Signing secret: an 86-character URL-safe string, returned only on this response. Use it verbatim as the HMAC key; see Webhook Security.
string
Fixed reminder that the secret is not shown again
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Identifier of the actor that created the endpoint, or null
string
Identifier of the actor that last updated the endpoint, or null
string
Reserved; always null.
string
Deletion timestamp. null for a newly created endpoint.

Errors

Request Example

Response Example