Webhook Endpoints

Create a webhook endpoint

Register a new webhook endpoint. HIFI delivers event notifications to the endpoint’s url for every event type listed in subscriptions.

A signing secret is generated on creation and returned once in the signingSecret field of this response only. Use it to verify the signature of incoming webhook deliveries. It is not returned by any other endpoint, so store it securely.

A profile may have at most 16 active webhook endpoints.

POST

webhook-endpoints

Create a webhook endpoint

curl --request POST \
  --url https://production.hifi.com/v3/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production events",
  "url": "https://api.example.com/webhooks/hifi",
  "description": "Receives all production event notifications",
  "subscriptions": [
    "USER.CREATED",
    "COMPLIANCE.STATUS.APPROVED",
    "OFFRAMP.STATUS.COMPLETED"
  ]
}
'

import requests

url = "https://production.hifi.com/v3/webhook-endpoints"

payload = {
    "name": "Production events",
    "url": "https://api.example.com/webhooks/hifi",
    "description": "Receives all production event notifications",
    "subscriptions": ["USER.CREATED", "COMPLIANCE.STATUS.APPROVED", "OFFRAMP.STATUS.COMPLETED"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Production events',
    url: 'https://api.example.com/webhooks/hifi',
    description: 'Receives all production event notifications',
    subscriptions: ['USER.CREATED', 'COMPLIANCE.STATUS.APPROVED', 'OFFRAMP.STATUS.COMPLETED']
  })
};

fetch('https://production.hifi.com/v3/webhook-endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production.hifi.com/v3/webhook-endpoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production events',
    'url' => 'https://api.example.com/webhooks/hifi',
    'description' => 'Receives all production event notifications',
    'subscriptions' => [
        'USER.CREATED',
        'COMPLIANCE.STATUS.APPROVED',
        'OFFRAMP.STATUS.COMPLETED'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://production.hifi.com/v3/webhook-endpoints"

	payload := strings.NewReader("{\n  \"name\": \"Production events\",\n  \"url\": \"https://api.example.com/webhooks/hifi\",\n  \"description\": \"Receives all production event notifications\",\n  \"subscriptions\": [\n    \"USER.CREATED\",\n    \"COMPLIANCE.STATUS.APPROVED\",\n    \"OFFRAMP.STATUS.COMPLETED\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://production.hifi.com/v3/webhook-endpoints")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Production events\",\n  \"url\": \"https://api.example.com/webhooks/hifi\",\n  \"description\": \"Receives all production event notifications\",\n  \"subscriptions\": [\n    \"USER.CREATED\",\n    \"COMPLIANCE.STATUS.APPROVED\",\n    \"OFFRAMP.STATUS.COMPLETED\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://production.hifi.com/v3/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production events\",\n  \"url\": \"https://api.example.com/webhooks/hifi\",\n  \"description\": \"Receives all production event notifications\",\n  \"subscriptions\": [\n    \"USER.CREATED\",\n    \"COMPLIANCE.STATUS.APPROVED\",\n    \"OFFRAMP.STATUS.COMPLETED\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "we_4mNpXwZ7bV1aLcs3Kf9dQ",
  "name": "Production events",
  "url": "https://api.example.com/webhooks/hifi",
  "description": "Receives all production event notifications",
  "subscriptions": [
    "USER.CREATED",
    "COMPLIANCE.STATUS.APPROVED",
    "OFFRAMP.STATUS.COMPLETED"
  ],
  "status": "ACTIVE",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z",
  "signingSecret": "whsec_9aB0xY4mNpXwZ7bV1aLdt3Kf9dQ2mNpXwZ7bV1aLcs"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Webhook endpoint details.

Fields for creating a webhook endpoint.

name

string

required

Human-readable name for the endpoint.

Example:

"Production events"

url

string<uri>

required

HTTPS URL that event notifications are delivered to.

Example:

"https://api.example.com/webhooks/hifi"

description

string

Optional description of the endpoint.

Example:

"Receives all production event notifications"

subscriptions

string[]

Event types this endpoint subscribes to.

A webhook event type an endpoint can subscribe to, such as ONRAMP.STATUS.COMPLETED. Call List webhook event types for every value accepted.

Example:

["USER.CREATED", "OFFRAMP.STATUS.COMPLETED"]

Response

Webhook endpoint created successfully. The signingSecret is returned only here.

A newly created webhook endpoint. Includes the signingSecret, which is returned only in this response and cannot be retrieved again.

string

Public ID of the webhook endpoint (prefixed with we_).

Example:

"we_4mNpXwZ7bV1aLcs3Kf9dQ"

name

string

Example:

"Production events"

url

string<uri>

Example:

"https://api.example.com/webhooks/hifi"

description

string

Example:

"Receives all production event notifications"

subscriptions

string[]

Event types this endpoint is subscribed to.

A webhook event type an endpoint can subscribe to, such as ONRAMP.STATUS.COMPLETED. Call List webhook event types for every value accepted.

Example:

["USER.CREATED", "OFFRAMP.STATUS.COMPLETED"]

status

enum<string>

Available options:

ACTIVE,

PAUSED,

DISABLED

Example:

"ACTIVE"

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

signingSecret

string

Secret used to verify the signature of incoming deliveries. Returned only on creation.

Example:

"whsec_9aB0xY4mNpXwZ7bV1aLdt3Kf9dQ2mNpXwZ7bV1aLcs"

⌘I

Create a webhook endpoint

curl --request POST \
  --url https://production.hifi.com/v3/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production events",
  "url": "https://api.example.com/webhooks/hifi",
  "description": "Receives all production event notifications",
  "subscriptions": [
    "USER.CREATED",
    "COMPLIANCE.STATUS.APPROVED",
    "OFFRAMP.STATUS.COMPLETED"
  ]
}
'

import requests

url = "https://production.hifi.com/v3/webhook-endpoints"

payload = {
    "name": "Production events",
    "url": "https://api.example.com/webhooks/hifi",
    "description": "Receives all production event notifications",
    "subscriptions": ["USER.CREATED", "COMPLIANCE.STATUS.APPROVED", "OFFRAMP.STATUS.COMPLETED"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Production events',
    url: 'https://api.example.com/webhooks/hifi',
    description: 'Receives all production event notifications',
    subscriptions: ['USER.CREATED', 'COMPLIANCE.STATUS.APPROVED', 'OFFRAMP.STATUS.COMPLETED']
  })
};

fetch('https://production.hifi.com/v3/webhook-endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production.hifi.com/v3/webhook-endpoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production events',
    'url' => 'https://api.example.com/webhooks/hifi',
    'description' => 'Receives all production event notifications',
    'subscriptions' => [
        'USER.CREATED',
        'COMPLIANCE.STATUS.APPROVED',
        'OFFRAMP.STATUS.COMPLETED'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://production.hifi.com/v3/webhook-endpoints"

	payload := strings.NewReader("{\n  \"name\": \"Production events\",\n  \"url\": \"https://api.example.com/webhooks/hifi\",\n  \"description\": \"Receives all production event notifications\",\n  \"subscriptions\": [\n    \"USER.CREATED\",\n    \"COMPLIANCE.STATUS.APPROVED\",\n    \"OFFRAMP.STATUS.COMPLETED\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://production.hifi.com/v3/webhook-endpoints")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Production events\",\n  \"url\": \"https://api.example.com/webhooks/hifi\",\n  \"description\": \"Receives all production event notifications\",\n  \"subscriptions\": [\n    \"USER.CREATED\",\n    \"COMPLIANCE.STATUS.APPROVED\",\n    \"OFFRAMP.STATUS.COMPLETED\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://production.hifi.com/v3/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production events\",\n  \"url\": \"https://api.example.com/webhooks/hifi\",\n  \"description\": \"Receives all production event notifications\",\n  \"subscriptions\": [\n    \"USER.CREATED\",\n    \"COMPLIANCE.STATUS.APPROVED\",\n    \"OFFRAMP.STATUS.COMPLETED\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "we_4mNpXwZ7bV1aLcs3Kf9dQ",
  "name": "Production events",
  "url": "https://api.example.com/webhooks/hifi",
  "description": "Receives all production event notifications",
  "subscriptions": [
    "USER.CREATED",
    "COMPLIANCE.STATUS.APPROVED",
    "OFFRAMP.STATUS.COMPLETED"
  ],
  "status": "ACTIVE",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z",
  "signingSecret": "whsec_9aB0xY4mNpXwZ7bV1aLdt3Kf9dQ2mNpXwZ7bV1aLcs"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}