Webhooks

The client.Webhooks sub-client provides full CRUD operations for webhook subscriptions. Webhooks allow the OneSend2U platform to push real-time event notifications to your application's HTTP endpoint when message states change, errors occur, or user actions are detected.

Available methods

Webhook events

Webhooks are triggered by combinations of event types and message states:

EventType enum

MessageProcessState (Statuses filter)

Creating a webhook

using OneSend2U.Sdk.Models.Enums;
using OneSend2U.Sdk.Webhooks.Models;

var webhook = await client.Webhooks.CreateAsync(new CreateWebhookRequest
{
    Name           = "Delivery Status Webhook",
    TargetEndPoint = "https://yourapp.example.com/webhooks/onesend2u",
    HttpMethod     = "POST",
    Status         = true,          // active
    NumberOfRetries = 3,
    RetryStrategy  = RetryStrategy.FixedDelay,
    RetryDelay     = 60,            // seconds between retries
    IsSigningEnabled = true,        // enable HMAC-SHA256 signature
    SigningSecretGracePeriodMinutes = 60,
    EventTypes = [EventType.Status],
    Statuses   = [MessageProcessState.Success, MessageProcessState.Error],
    DeploymentEnvironmentId = deploymentEnvId
});

Console.WriteLine($"Webhook created: {webhook.Id}");
Console.WriteLine($"Signing enabled: {webhook.IsSigningEnabled}");

CreateWebhookRequest fields

Retry strategies

WebhookResponse fields

GetAsync and CreateAsync return a WebhookResponse with these fields:

Updating a webhook

Pass the ConcurrencyStamp from the GetAsync response to prevent conflicting updates:

var existing = await client.Webhooks.GetAsync(webhookId);

await client.Webhooks.UpdateAsync(webhookId, new UpdateWebhookRequest
{
    Name             = existing.Name!,
    TargetEndPoint   = "https://yourapp.example.com/webhooks/v2",
    HttpMethod       = existing.HttpMethod ?? "POST",
    Status           = existing.Status,
    NumberOfRetries  = existing.NumberOfRetries,
    RetryStrategy    = existing.RetryStrategy,
    RetryDelay       = existing.RetryDelay,
    EventTypes       = existing.EventTypes,
    Statuses         = existing.Statuses,
    ConcurrencyStamp = existing.ConcurrencyStamp,
    DeploymentEnvironmentId = existing.DeploymentEnvironmentId
});

Deleting a webhook

await client.Webhooks.DeleteAsync(webhookId);
Console.WriteLine("Webhook deleted.");

Testing a webhook

Sends a synthetic test event to the webhook endpoint without creating a real notification. You pass the full WebhookResponse object (fetch it first with GetAsync).

WebhookTestResponse fields:

// Fetch the webhook first — TestAsync takes the full WebhookResponse
var webhook = await client.Webhooks.GetAsync(webhookId);
var testResult = await client.Webhooks.TestAsync(webhook);

Console.WriteLine($"Test status code: {testResult.StatusCode}");
Console.WriteLine($"Reason: {testResult.ReasonPhrase}");

if (testResult.ErrorMessage != null)
    Console.WriteLine($"Delivery error: {testResult.ErrorMessage}");
else
    Console.WriteLine($"Response body: {testResult.FormattedContent}");

Rotating the signing secret

Use RotateSigningSecretAsync to generate a new HMAC signing secret. The previous secret stays valid for the duration of SigningSecretGracePeriodMinutes so your endpoint can drain in-flight events before switching.

var rotated = await client.Webhooks.RotateSigningSecretAsync(webhookId);
Console.WriteLine($"New secret: {rotated.SigningSecret}");
// Previous secret remains valid during grace period — validate against both secrets in the meantime

Secret rotation

When you rotate a signing secret, the previous secret remains valid for the configured grace period (SigningSecretGracePeriodMinutes). During this window, validate incoming payloads against both secrets:

var webhook = await client.Webhooks.GetAsync(webhookId);

// During grace period, HasPreviousSigningSecret will be true.
// Validate against both secrets to avoid dropping valid events.
var result = WebhookSignatureValidator.Validate(
    payload:         requestBody,
    secrets:         [webhook.SigningSecret, previousSecret],
    signatureHeader: request.Headers["X-OneSend2U-Webhook-Signature"],
    timestampHeader: request.Headers["X-OneSend2U-Webhook-Timestamp"],
    webhookIdHeader: request.Headers["X-OneSend2U-Webhook-Id"]);

See Webhook Verification for the full signature validation guide.