Retry Webhook - Capa.fi

Retry a failed webhook notification

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry \
  --header 'partner-api-key: <api-key>'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry"

headers = {"partner-api-key": "<api-key>"}

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

print(response.text)

const options = {method: 'POST', headers: {'partner-api-key': '<api-key>'}};

fetch('https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry', 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://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "partner-api-key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry"

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

	req.Header.Add("partner-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry")
  .header("partner-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry")

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

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'

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

{
  "success": true,
  "data": {
    "id": "8374f327-38bd-4b0b-b8a7-2524599eb903",
    "status": "PENDING",
    "retryAttempts": 0,
    "manualRetryCount": 2,
    "payload": {
      "type": "TRANSACTION",
      "event": "CREATED_ON_RAMP",
      "externalUserId": "18c54df0-1e62-4fee-8864-9b7512a0748c",
      "transactionId": "14f6ba28-d285-4658-8dd7-8a1d903838c8",
      "firstName": "Martin",
      "lastName": "Smith"
    },
    "latestErrorPayload": null,
    "lastManualRetryAt": "2026-01-15T10:40:00.000Z",
    "version": 2,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:40:00.000Z"
  }
}

POST

api

partner

webhook-notifications

{id}

retry

Retry a failed webhook notification

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry \
  --header 'partner-api-key: <api-key>'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry"

headers = {"partner-api-key": "<api-key>"}

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

print(response.text)

const options = {method: 'POST', headers: {'partner-api-key': '<api-key>'}};

fetch('https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry', 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://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "partner-api-key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry"

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

	req.Header.Add("partner-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry")
  .header("partner-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/webhook-notifications/{id}/retry")

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

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'

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

{
  "success": true,
  "data": {
    "id": "8374f327-38bd-4b0b-b8a7-2524599eb903",
    "status": "PENDING",
    "retryAttempts": 0,
    "manualRetryCount": 2,
    "payload": {
      "type": "TRANSACTION",
      "event": "CREATED_ON_RAMP",
      "externalUserId": "18c54df0-1e62-4fee-8864-9b7512a0748c",
      "transactionId": "14f6ba28-d285-4658-8dd7-8a1d903838c8",
      "firstName": "Martin",
      "lastName": "Smith"
    },
    "latestErrorPayload": null,
    "lastManualRetryAt": "2026-01-15T10:40:00.000Z",
    "version": 2,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:40:00.000Z"
  }
}

Manually retries a FAILED webhook notification, queuing it for immediate re-delivery to your configured webhook URL. The automatic retry cycle is reset and manualRetryCount is incremented.

Important Notes

Status requirement: The notification must be in FAILED status. Attempting to retry a SENT, PENDING, or NOT_SENT notification returns a 409.
Manual retry limit: Each notification allows a maximum of 3 manual retries. Once reached, the endpoint returns 409 and the notification cannot be retried again.
Rate limit: A maximum of 10 manual retries per partner per minute is enforced. Exceeding this returns 429.
Automatic retry reset: On a successful retry request, retryAttempts is reset to 0 and latestErrorPayload is cleared, giving the notification a fresh delivery cycle.

When to Retry vs. When to Contact Support

Retry when:

Your endpoint was temporarily unavailable (e.g. a deployment, a transient 5xx).
You fixed a bug in your webhook handler and need the event reprocessed.
The latestErrorPayload shows a recoverable error (connection timeout, 503, etc.).

Contact support when:

Your webhook URL has changed — update it first via PUT /api/partner/v2/webhook-settings, then retry.
The event payload is stale and the corresponding transaction has already been handled through another channel.
You have exhausted all 3 manual retries and still cannot receive the notification.

Error Codes

Common Errors

HTTP Status	Code	Message
401	`UNAUTHORIZED`	”API Key is missing”
401	`UNAUTHORIZED`	”Invalid API Key format”
401	`UNAUTHORIZED`	”Invalid API Key”
403	`INVALID_PARTNER_FLOW`	”The partner has an invalid flow.”

Endpoint-Specific Errors

HTTP Status	Code	Message
404	`NOT_FOUND`	”Webhook notification not found”
409	`CONFLICT`	”Notification is not in FAILED status”
409	`CONFLICT`	”Partner webhook notification has reached the maximum number of manual retries (3)“
429	`TOO_MANY_REQUESTS`	”Rate limit exceeded. Try again in a few seconds.”

Authorizations

partner-api-key

string

header

required

API key for the affiliated partner performing the request.

Path Parameters

string

required

The webhook notification ID to retry

Example:

"8374f327-38bd-4b0b-b8a7-2524599eb903"

Response

Notification successfully queued for re-delivery. Returns the updated notification with status reset to PENDING.

success

boolean

Example:

true

data

object

Show child attributes

Get Webhook

⌘I

​Important Notes

​When to Retry vs. When to Contact Support

​Error Codes

​Common Errors

​Endpoint-Specific Errors